Start Writing Your 1st UMAT Abaqus

Start writing your 1st Abaqus UMAT

First, I strongly recommend reading this article to get familiar with the process of writing a subroutine in Abaqus:

Start Writing a Subroutine in Abaqus: Basics and Recommendations

UMAT stands for User Material. Remember, we use UMAT when none of the existing material models included in the ABAQUS material library accurately represents the behavior of the material to be modeled. In a single word, We need to calculate the DDSDDE matrix in our UMAT subroutine.(DDSDDE UMAT)

What does the UMAT Abaqus do? Obviously, the philosophy behind the UMAT Abaqus subroutine is that the material model developer should be concerned only with the development of the material model and not the development and maintenance of the FE model. Referring to the article How to start writing a subroutine (Section 3), you can see we use a UMAT in the stress calculation step. So, the main output of a UMAT subroutine is the stress tensor. In the process, Abaqus also needs to define the (consistent) Jacobian to continue its incremental scheme. (Since we assumed this is the first time you start writing a UMAT, we start from the simplest one and present our step-by-step example in a pure elastic material, precisely called an isotropic linear elastic material model. For more advanced material models (plasticity, failure, element removal, brittle materials, etc.) I refer you to UMAT Subroutine (VUMAT Subroutine) introduction package)

Figure 1: UMAT subroutine workflow

NOTE: Although this article will help you to start writing UMAT Abaqus, this subroutine is a little complicated and based on our feedback from hundreds of students and researchers during the last 4 years, UMAT Subroutine Free Course has saved a lot of time when writing UMAT in Abaqus, and prepared codes in this package without any bugs or errors can speed up your UMAT writing for simulation.

Generally, to write a newly developed UMAT, you should follow these steps:

1. Knowing well the material model theory for our UMAT Abaqus

You should master all the aspects of the constitutive model for your material. In this step, the material model is represented in concise mathematical equations.

EXAMPLE: Isotropic Linear Elastic Material (Theory)

Isotropic simply means the properties of the material are same in all directions. And, Elastic simply means that when the material is unloaded, it will return to its original (Undeformed) state. In addition, Linear means that the relation between mechanical load and deformation of a material can be described by Hooke’s law. In a stress-strain literature we can state Hook’s law as:

Stress = [Constant] × Strain

For our case (isotropic linear elastic material), we need two independent material parameters to define the state:

1. Constant that measures the resistance in the direction of load » Young’s modulus (E)

2. Constant measures how much the material is dragged sideways for a vertical (perpendicular) load » Poisson’s ratio (v).

Eventually, Hooke’s law in the form of these two elastic constants is,

And that is enough for writing our simple subroutine. The matrix C is the proportional factor that convert strain to stress. It is called stiffness matrix, i.e. how the material resists deformation. We use this for adding the DDSDDE matrix to our Fortran code, which we will discuss further.

You can see more details about the theory and equations in Workshop 1: Writing UMAT Subroutine for Isotropic Isothermal Elasticity of our UMAT Free

Or you can get the Workshop files directly here:

2. Getting Familiar with UMAT Abaqus parameters (Inputs/Outputs)

We should restate our material model in UMAT language. So, you need to understand parameters name and their structures (are they scalar, vector or matrix? their dimension?).

As we talked in the article How to start writing a subroutine, the first step in writing any subroutine will be referring to the Abaqus Documentation. Therefore, you should find the UMAT section and review the guide to have a know-how of UMAT parameters.

Here, in a most general way, I sort all parameters for a UMAT in 4 distinguished groups:

A. Parameters that are available by Abaqus to our UMAT

You can see all the parameters passed into UMAT in the documentation. The most important and practical ones are:

Reminder ………………………………………………………………………………………………………………………….

In FORTRAN, we define scalars as single names, like ALPHA, SDV, etc. Vectors are defined by a name and their dimensions, like DMGQ(3), STRE(5), etc. For 2D matrices, the No. of rows and columns should be clarified when defining these variables: STRM(6,6), DDSDDL (4,4), …

Read more:  Abaqus Fortran “Must-Knows” for Writing Subroutines

…………………………………………………………………………………………………………………………………………

1) NTENS

This is the size of the stress or strain component array and reflects the overall dimension of the Abaqus model into UMAT. For example, that is 6 for a general 3D and 4 for a simplified plane strain (2D) model.

In the stress and strain arrays and in the DDSDDE  matrix(discuss soon), direct components are stored first, followed by shear components. There are NDI direct and NSHR engineering shear components. So,

NTENS = NDI + NSHR

2) STRESS(NTENS)

A vector form of stress tensor at the start of increment.

It has NTENS elements. For a general 3D model, we need 6 values for stress (3 normal and 3 shear) so this vector will have 6 elements.

3) STRAN(NTENS), DSTRAN(NTENS)

STRAN is a vector form of strain tensor at the start of increment. DSTRAN is the increment (variation) of strain .

4) TIME(2), DTIME

Respectively, total and incremental values of time. TIME is a 2-element vector; the first element, i.e. TIME(1) states the value of step time and the second, i.e. TIME(2), is the value of total time, both at the beginning of the current increment.

Note. There are many other variables that Abaqus pass into UMAT and are not discussed here, like COORDS (An array containing the coordinates of the point of calculation). According to your material, you may need to use them either. For example, if you are working on a FGM (Functionally Graded Material: material whose properties change gradually with respect to its dimensions) you need to use COORDS(3) parameter too.

Ok, guys, here in the following video, you can see some basics about writing UMAT Abaqus in the first lesson of the UMAT subroutine video training package; do not miss this useful 25-minutes video:

It seems you have enjoyed the video; if you want to see more chapters of this training package, you can check and click on the Umat subroutine introduction on Abaqus Free Course.

B. Parameters must be calculated and updated by UMAT Abaqus (outputs)

In a simple UMAT, these parameters are

1) STRESS(NTENS)

A vector form of stress tensor with NTENS elements. The dimension (NTENS) comes from the dimension of the model. For a general 3D model, we need 6 values for stress (3 normal and 3 shear) so this vector will have 6 elements.

At the first, STRESS is the stress tensor at the beginning of the increment. Then, we update it as the stress tensor at the end of the increment.

2) DDSDDE(NTENS,NTENS)

A 2D format of Jacobian matrix with NTENS row and NTENS column called DDSDDE matrix.

For small-deformation problems (e.g., linear elasticity) or large-deformation problems with small volume changes (e.g., metal plasticity), the consistent Jacobian can be calculated as:

Where, ∆σ is the increment in (Cauchy) stress and ∆ε is the increment in strain. The variable DDSDDE(I,J) in the context of DDSDDE Abaqus UMAT specifies how the Ith stress component changes at the end of the time increment due to a tiny perturbation of the Jth component in the strain increment array.

As you may guess, calculation of the consistent Jacobian or DDSDDE matrix can be the main challenge in writing a UMAT. This article provides a set of guidelines that will make the process of writing DDSDDE UMAT easier for you. An effective recommendation is to define variables for the elements of the DDSDDE matrix. This can make your code more organized, as demonstrated in the example code provided in section 3.

Note. There are other variables that Abaqus can get from a UMAT and we did not discuss here, like RPL (Volumetric heat generation caused by mechanical working in a thermo-mechanical material model). According to your material you may need to use them either.

C. Parameters entered through Abaqus model definition & sent to UMAT

PROPS (NPROPS)

User-specified array of material constants associated with this user material with NPROPS (number of material constants) elements.

When defining our model through Abaqus CAE, we enter these parameters in Property module (we will discuss more, later).

D. Parameters defined by user that is needed in next increments or we want Abaqus to save their values and later can be seen in results

STATEV(NSTATV)

An array containing the Solution-Dependent state Variables (SDV). Abaqus pass in these parameters as the values at the beginning of the increment and at the end, return them as the values at the end of the increment. NSTATV (number of solution-dependent state variables associating with this material type) define the size of the array.

We should specify the number of needed state variable (if any) when defining our model through Abaqus/CAE in Property module (we will discuss more, later).

After completing the analysis, Abaqus can visualize the values of state variables (named as SDV1, SDV2, … in Abaqus/CAE) calculated during increments.

Figure 2: Parameter types in UMAT

EXAMPLE: Isotropic Linear Elastic Material (Required Outputs/inputs)

Here we will only use DDSDDE matrix, STRESS and STRAN. The STRAN matrix is an input to the UMAT. Then, UMAT updates the STRESS matrix (using DDSDDE matrix and STRAN ) and returns it as an output.

In this simple problem, we can easily find Jacobian(DDSDDE matrix) from elastic stress-strain relation:

So, here we can use a single notation and use DDSDDE matrix to find STRESS too.

In addition, we use PROPS(1) and PROPS(2) as Young’s modulus I and Poisson’s ratio (v), respectively. For that, we will enter the values when defining the material in Abaqus/CAE later. See figure 4. Implementation in Abaqus & Compilation.

Ok, the main parameters of input and output of UMAT subroutine is introduced now, but there are lots of points to writing a correct and complete UMAT subroutine(DDSDDE UMAT); especially if you need to write a VUMAT, take a look at our comprehensive training package for UMAT/VUMAT:

3. Developing FORTRAN code of the UMAT in Abaqus

In this step, the theoretical model for our material is implemented in Fortran. We will pass the .for file generated in the next step to Abaqus to be compiled and then used in Abaqus/Standard analysis.

As we explained before, in How to start writing subroutines…, the header part of UMAT in Abaqus, which is a template from documentation, remains unchanged. We need to define our main outputs (STRESS, DDSDDE Abaqus) or any other mandatory outputs for the considered material model.

EXAMPLE: Isotropic Linear Elastic Material (Fortran code)

In this material model UMAT, we just define elements of DDSDDE Abaqus or DDSDDE UMAT and calculate STRESS elements using STRAND :

Figure 3: Linear-Elastic-Fortran-Code

This piece of code will replace the “user coding to define DDSDDE matrix, STRESS,…” part of the template from the documentation. See the article How to start writing subroutines (Section 5) again.

You can download the complete UMAT file, including the DDSDDE UMAT, to check by yourself from here.

Save this UMAT Abaqus. The path to this file will be later entered in the Abaqus Job settings.

4. Implementation in Abaqus & Compilation

After successfully developing the UMAT, the code must be incorporated into Abaqus to correctly compile a working Abaqus analysis. When defining the Abaqus job, you can add the developed UMAT. After Submitting the job, the UMAT will be compiled into a working executable by Abaqus automatically and can then be used to run the FEA simulation. After normally defining your FEM model in Abaqus/CAE, generally, you need to pass 4 more steps within Abaqus/CAE to incorporate a UMAT in your analysis:

i. Define a User Material

Say Abaqus that you will use a UMAT as a material model. You can also use other material models of Abaqus if there is no intervention. For example, you can use Abaqus’s own model for elasticity but develop a UMAT to model a very specific plasticity model.

From Property module, when defining a material, from General tab select User Material. That is all you should do.

Figure 4: Define User-Material in Abaqus CAE

ii. Define inputs (Mechanical Constants) for UMAT in Abaqus

When you select User Material as a material model for your problem, you can add as many constants as you wish in Data section. Type under Mechanical Constants the values you want to pass into written UMAT. After entering any data, you can press Enter to add a new row. These values then will be accessible through UMAT via PROPS array (PROPS(1), PROPS(2),…).

iii. Define the No. of state variables

Many mechanical constitutive models may require the storage of Solution-Dependent state Variables (SDV) such as plastic strains, back stress, saturation values, etc. in rate constitutive forms or historical data for theories written in integral form. You should allocate storage for these variables in the associated material definition. There is no restriction on the number of state variables.
The number of such variables required at the points is entered as part of the material definition. In Abaqus/CAE, Property module when defining a material, from General tab select Depvar. Then select the required quantity in Number of solution-dependent state variables.

Figure 5: Defining Depvar in Abaqus/CAE UMAT in Abaqus

State variables can be output to the output database (.odb) file using output identifiers SDV. You can ask Abaqus to visualize them later after completion of the job. In Step module, after defining your analysis type, from Field Output Manager, you can edit the F-Output-1 created automatically by Abaqus:

Figure 6: Requesting SDV in Field Output

Remember that the SDV in Abaqus/CAE is exactly the same as STATEV in Abaqus Subroutine Interface. That is just a difference in naming by developers of Abaqus.

iv. Give the Path of UMAT to Abaqus

Like any other subroutine, when creating an Abaqus job, you should provide the path of  the UMAT to Abaqus. Abaqus can then read the subroutine and update the DDSDDE matrix per iteration. You can include one or more UMATs in a model by specifying the name of a Fortran source file that contains the subroutines.

EXAMPLE: Isotropic Linear Elastic Material (Implementation)

As we will discuss in section 6 (Examining UMAT results), at first, we start from a very simple model like simple tension (displacement-based) on one-element mode. After building our FEM model in Abaqus/CAE like any other model without UMAT, we should (we do not need any state variable in this simple UMAT):

1. Define a User Material from the Property module

2. Define two Mechanical Constants as inputs for our elastic model UMAT: E and Nu

3. Give the Path of our written UMAT to Abaqus when defining the job.

5. Testing and debugging UMAT Abaqus subroutine

Keep in mind that writing a UMAT in Abaqus is exactly like developing a piece of code in Fortran. So, when you finish typing your code, the main task starts! After the first run, you may encounter compiling errors, complaining by compiler about structures DDSDDE Matrix or nested loops of DDSDDE Matrix and so on. Be patient; this is really normal even for experienced UMAT developers.

Figure 7: Problem during compilation Error in Job Monitor

When you are facing an error and you are not sure about the cause, in a most easygoing manner, you can check the values by using write command to write the variable values into .msg file. We will discuss most important Fortran commands that are really handy when writing a UMAT Abaqus (and also any subroutine) in an article later.

6. Examining UMAT Abaqus results and verification

In this step, we will verify the compiled UMAT in Abaqus by running a couple of examples and compare the results against analytical, experiment or semi-analytical (predicted) results. UMAT verification is a crucial step in any UMAT development in order to guarantee a high level of confidence and quality in the developed material model.

Always start verifying the UMAT with a small (one element) model.

1. Run tests with all displacements prescribed to verify the integration algorithm for stresses and state variables (if any).

Suggested tests include:

» Uniaxial tensile/compressional test

» Biaxial/triaxial in two/three direction especially when anisotropy is present.

» Simple shear test

2. Run similar tests with load prescribed to verify the accuracy of the Jacobian.

3. Compare test results with analytical solutions or standard ABAQUS material models, if possible. If the above verification is successful, apply to more complicated problems.

EXAMPLE: Isotropic Linear Elastic Material (Verification)

This very simple UMAT yields exactly the same results as the Abaqus elastic model. So, we can verify our subroutine by comparing the results with Abaqus results from the native elastic model.

For example, we can check simple tension, simple shear and then run a more complicated 3D model and compare the results.

This simple UMAT can be used in 3D and plane strain models. It is usually straightforward to write a single routine that handles (generalized) plane strain, axisymmetric, and three-dimensional geometries. Generally, plane stress must be treated as a separate case because the stiffness coefficients are different, which affects the DDSDDE matrix.

Read More: Explore our comprehensive Abaqus tutorial page, featuring free PDF guides and detailed videos for all skill levels. Discover both free and premium packages, along with essential information to master Abaqus efficiently. Start your journey with our Abaqus tutorial now!

7. Abaqus VUMAT Subroutine

As we discussed in the previous section, UMAT is a powerful tool for implementing custom material models by defining a material’s stress-strain relationship through user-defined equations. However, VUMAT is the next step when dealing with dynamic loading scenarios, such as those involving dynamic impact, shock loading, or materials that exhibit nonlinear behaviors under high strain rates. Let’s break down the issue together to understand it better.

Imagine you have a sample and want to see how it reacts under dynamic loading by figuring out its stress-strain behavior or load-displacement curve(fig 8). A great starting point is to have data from the lab or published experiments that provide key points on the curve. This information can easily be utilized in Abaqus.

Figure 8: Stress-strain behavior [Ref]

If you’re looking for more accurate solutions, it’s important to understand the material’s behavior or its constitutive equations. Every material behaves according to certain rules, and having the right equations is essential. If you can define your material’s properties in Abaqus using a well-known model like the Johnson-Cook equation, you just need to plug in the parameters. From there, Abaqus takes care of calculating the responses at all points based on that equation(fig 9).

Figure 9: Apply material properties if defined in the Abaqus library

Figure 10 shows how Abaqus and VUMAT work together by sharing and updating important material variables. Here’s a simple breakdown of the process: Abaqus hands over the old variables—like stress, temperature, and any state-dependent variables—that describe the current state of the material. These serve as the starting point for VUMAT’s calculations.  Using custom equations, VUMAT takes these inputs and calculates new values for stress, temperature, and other state variables. Once VUMAT has processed this information, it sends the updated variables back to Abaqus for further analysis and to keep the simulation going smoothly.

To make things clearer, we can think of the variables in three groups: “Variables to be defined,” “Variables that can be updated,” and “Variables passed in for information,” just like what’s explained in UMAT. It’s a great way to manage data and ensure everything runs efficiently!

Figure 10: how VUMAT work [Ref]

8. What’s the difference between UMAT and VUMAT?

Let’s start with UMAT, which stands for User Material. This subroutine is perfect for implicit analyses, often used in static or quasi-static situations (fig 11). It lets you define complex material behaviors, like plasticity or viscoelasticity, by detailing how stress and strain interact. If your project doesn’t involve large deformations or fast dynamics, UMAT is your go-to choice. It’s commonly used in structural simulations where solutions are approached directly or through iterations.

Figure 11: An example of quasi-static problem

Conversely, we have VUMAT, tailored for explicit analyses. This is particularly useful for scenarios involving large deformations(fig 12), high-speed events, or dynamic simulations. Unlike the implicit solver—where solutions are computed step-by-step—the explicit solver used in VUMAT calculates each time step independently. This makes it an excellent fit for modeling impacts, explosions, and other fast-paced, dynamic behaviors.

Figure 12: an example of a large deformations simulation

Both UMAT and VUMAT are written in Fortran, allowing you to create custom material models. Ultimately, the choice between the two comes down to the nature of your analysis—whether it’s static or dynamic.

9. Quick view VUMAT subroutine interface and essential Variables to be defined

In Abaqus, when working with custom material models, you can explore the Abaqus documentation to find the VUMAT subroutine interface. To do this, go to the SIMULIA User Assistance > Abaqus> User Subroutines > Abaqus/Explicit User Subroutines > VUMAT. You can see the VUMAT subroutine interface below.

subroutine vumat(
C Read only (unmodifiable)variables -
1 nblock, ndir, nshr, nstatev, nfieldv, nprops, jInfoArray,
2 stepTime, totalTime, dtArray, cmname, coordMp, charLength,
3 props, density, strainInc, relSpinInc,
4 tempOld, stretchOld, defgradOld, fieldOld,
5 stressOld, stateOld, enerInternOld, enerInelasOld,
6 tempNew, stretchNew, defgradNew, fieldNew,
C Write only (modifiable) variables -
7 stressNew, stateNew, enerInternNew, enerInelasNew )
C
include 'vaba_param.inc'
parameter (i_info_AnnealFlag = 1, 
* i_info_Intpt = 2, ! Integration station number
* i_info_layer = 3, ! Layer number
* i_info_kspt = 4, ! Section point number in current layer
* i_info_effModDefn = 5, ! =1 if Bulk/ShearMod need to be defined
* i_info_ElemNumStartLoc = 6) ! Start loc of user element number
C
dimension props(nprops), density(nblock), coordMp(nblock,*),
1 charLength(nblock), dtArray(2*(nblock)+1), strainInc(nblock,ndir+nshr),
2 relSpinInc(nblock,nshr), tempOld(nblock), 
3 stretchOld(nblock,ndir+nshr),
4 defgradOld(nblock,ndir+nshr+nshr),
5 fieldOld(nblock,nfieldv), stressOld(nblock,ndir+nshr),
6 stateOld(nblock,nstatev), enerInternOld(nblock),
7 enerInelasOld(nblock), tempNew(nblock),
8 stretchNew(nblock,ndir+nshr),
8 defgradNew(nblock,ndir+nshr+nshr),
9 fieldNew(nblock,nfieldv),
1 stressNew(nblock,ndir+nshr), stateNew(nblock,nstatev),
2 enerInternNew(nblock), enerInelasNew(nblock), jInfoArray(*)
C
character*80 cmname
C
pointer (ptrjElemNum, jElemNum)
dimension jElemNum(nblock)
C
lAnneal = jInfoArray(i_info_AnnealFlag) 
iLayer = jInfoArray(i_info_layer)
kspt = jInfoArray(i_info_kspt)
intPt = jInfoArray(i_info_Intpt)
iUpdateEffMod = jInfoArray(i_info_effModDefn)
iElemNumStartLoc = jInfoArray(i_info_ElemNumStartLoc)
ptrjElemNum = loc(jInfoArray(iElemNumStartLoc))

do 100 km = 1,nblock
user coding
100 continue

return
end

9.1. The first part of the interface

The interface contains the subroutine name along with all argument information provided at the beginning of the increment.

subroutine vumat(
C Read only (unmodifiable)variables -
1 nblock, ndir, nshr, nstatev, nfieldv, nprops, jInfoArray,
2 stepTime, totalTime, dtArray, cmname, coordMp, charLength,
3 props, density, strainInc, relSpinInc,
4 tempOld, stretchOld, defgradOld, fieldOld,
5 stressOld, stateOld, enerInternOld, enerInelasOld,
6 tempNew, stretchNew, defgradNew, fieldNew,
C Write only (modifiable) variables -
7 stressNew, stateNew, enerInternNew, enerInelasNew )
C

As we said, various variables are involved When you define a custom material model in Abaqus using the VUMAT subroutine (for dynamic analysis). As we mentioned, these variables can be classified differently in the first part of the interface: some need to be defined, some can be updated, and some are passed in to provide information to the subroutine.

Let’s take a look at these three categories of variables and explain each one clearly!

9.2. Variables to be defined (VUMAT subroutine)

stressNew: The most important variable that should be defined at the end of the increment is Cauchy stress. This variable holds the stress at the integration point. The subroutine uses this value to calculate how the material resists deformation. We must define this variable at the end of the increment (fig 13).

Figure 13: Variables to be defined: stressNew , Variables passed in for information: stressOld

StateNew: State variables are an array where we can save values to use in the next increment. The length of this array is defined in the GUI (fig 14). These are state variables that describe the material’s internal state, like plastic strain, damage, or any history-dependent variables. For example, in a plasticity model, you might have a state variable that tracks the accumulated plastic strain. (fig 14).

Figure 14: Variables to be defined: stateNew, Variables passed in for information: stateOld

9.3. Variables passed in for information (VUMAT)

StressOld: Stress tensor at each material point at the beginning of the increment(fig 13). The stress state of the material at the start of the increment is used as the initial reference for the calculations in the VUMAT subroutine. The material’s response is then updated based on this initial stress state as the simulation progresses, and the stress is modified throughout the increment depending on the material behavior you define within VUMAT.

StateOld: State variables at each material point at the beginning of the increment.(fig 14)

Strainlnc: The Strainlnc variable as input contains the strain increment(the strain increment typically refers to the change in strain between two consecutive steps or increments in a simulation.) for the change in the strength tensor during these increments. The name of the material defined in the GUI is passed to VUMAT by Cmname.

Figure 15: strain increment

nblock: The nblock variable, unlike UMAT, which is called separately for each material point, VUMAT receives information for a group of material points as input, and the code should update all of them. The number of these points is stored in the nblock variable (fig 16).

Figure 16: nblock variable define

ndir, nshr: These two variables show the dimensions of the stress and strain tensors. The first one shows the number of normal components of the stress tensor the second one shows the number of sheer components of the stress tensor. To calculate the total number of stress components, we should sum the first and second; for example, in a three-dimensional problem, the stress array contains six components. Please note the arrangement of sheer components in a VUMAT subroutine. This array has three normal components and three shear components for six stress components.

Figure 17: ndir, nshr variables

Props: The following variable in fig 18 for material constants is defined in the GUI to the VUMAT. For example, in the VUMAT subroutine, the material properties (props) and other variables like density should be correctly indexed and used. If you have variables like E (Young’s modulus), (Poisson’s ratio), and yield (yield stress), make sure they correspond to the correct props array indices.

Figure 18: props variable define

In fig 19, This statement tells the Abaqus execution procedure to include this file. This file, installed during the Abaqus installation, contains important installation parameters. This line is necessary for all the VUMAT Subroutines.

Figure 19: the necessary part for all the VUMAT Subroutines

9.4. Variables that can be updated (VUMAT subroutine)

enerInternNew (nblock): represents the internal energy per unit mass at each material point at the end of the current increment. This variable tracks the energy stored in the material due to deformation. It includes contributions from elastic strain energy and other recoverable energy stored in the material’s state.

enerInelasNew: represents the dissipated inelastic energy per unit mass at each material point at the end of the current increment. This variable measures the energy dissipated due to irreversible processes, such as plastic deformation, damage, or other inelastic behaviors.

9.5. The second part of the interface (VUMAT)

The next part of the interface is defined to determine the dimensions of the all variables; please note that most of the variables are one or 2-dimensional arrays with one length equal to nblock; this means these variables are related to the nblock number of points.

C
dimension props(nprops), density(nblock), coordMp(nblock,*),
1 charLength(nblock), dtArray(2*(nblock)+1), strainInc(nblock,ndir+nshr),
2 relSpinInc(nblock,nshr), tempOld(nblock), 
3 stretchOld(nblock,ndir+nshr),
4 defgradOld(nblock,ndir+nshr+nshr),
5 fieldOld(nblock,nfieldv), stressOld(nblock,ndir+nshr),
6 stateOld(nblock,nstatev), enerInternOld(nblock),
7 enerInelasOld(nblock), tempNew(nblock),
8 stretchNew(nblock,ndir+nshr),
8 defgradNew(nblock,ndir+nshr+nshr),
9 fieldNew(nblock,nfieldv),
1 stressNew(nblock,ndir+nshr), stateNew(nblock,nstatev),
2 enerInternNew(nblock), enerInelasNew(nblock), jInfoArray(*)
C

For example, density(n-block) is a one-dimensional array with a length of nblock. stressold and stressnew are two-dimensional arrays with a length of nblock, ndir (Number of direct components in a symmetric tensor) plus nshr (Number of indirect components in a symmetric tensor). 

Input and output to stateNew variables are two-dimensional arrays with lengths of nblock by nstatev; this indicates the number of state variables that the material model uses. These variables represent the material’s internal state, such as plastic strain, damage, temperature, etc., depending on the material model you define. (stateNew(nblock, nstatev)).

Your Turn!

1) Try to develop a simple elastic UMAT Abaqus like what we discussed for 3D and PE (plane strain) models for an isotropic PS (plane stress) model. Follow exactly the steps.

2) Combine two UMAT (3D, PE + PS) into one single Fortran file. Test it with PE and PS models in Abaqus.

Tip: Refer to the explanation beneath NTENS parameter in 2. Getting Familiar with UMAT Abaqus parameters (Inputs/Outputs). Try to use an IF structure to ask Abaqus whether it is a plane stress problem or not.

If you are looking for more information about defining DDSDDE in UMAT code(DDSDDE UMAT) and or you need to write a VUMAT, take a look at our comprehensive training package for UMAT/VUMAT:

If you have any questions about writing UMAT in Abaqus or DDSDDE matrix in UMAT, comment here below, or are interested in this article, please share your idea in the comments.

Get the second part of this article as a PDF: start writing your 1st-umat in abaqus construction

Appendix: Sample code

Here’s a more detailed example of a UMAT subroutine in Fortran for a linear elastic material:

SUBROUTINE UMAT (STRESS, DSTRN, STATEV, DDSDDE, SEED, PRESCAL, 
PROPS, NPROPS, NSV, NSTATEV, NOEL, NPT, NLHS, 
IPOL, DDDODT, REF, DRDY, T, DT, TOL, TETRA, 
HIDID, JELEMEN, MATYP, USERWORK)

! Include statements for Abaqus constants and material properties
INCLUDE 'ABA_PARAM.INC'
INCLUDE 'USER_MATERIAL_PROP.INC' ! Replace with your property file

REAL, DIMENSION(6) :: STRESS, DSTRN
REAL, DIMENSION(:) :: STATEV, DDSDDE !(:) allows variable size
REAL, DIMENSION(NPROPS) :: PROPS

! Elastic constants (Young's modulus and Poisson's ratio)
YOUNG_MODULUS = PROPS(1)
POISSONS_RATIO = PROPS(2)

! Material needs no internal state variables (set NSV to 0)
NSV = 0

! Calculate bulk modulus (derived property)
BULK_MODULUS = YOUNG_MODULUS / (3.0 * (1.0 - POISSONS_RATIO))

! Update stress based on strain increment
STRESS(1) = YOUNG_MODULUS * DSTRN(1) + POISSONS_RATIO * (DSTRN(2) + DSTRN(3))
STRESS(2) = YOUNG_MODULUS * DSTRN(2) + POISSONS_RATIO * (DSTRN(1) + DSTRN(3))
STRESS(3) = YOUNG_MODULUS * DSTRN(3) + POISSONS_RATIO * (DSTRN(1) + DSTRN(2))
STRESS(4) = POISSONS_RATIO * YOUNG_MODULUS * (DSTRN(1) + DSTRN(2))
STRESS(5) = POISSONS_RATIO * YOUNG_MODULUS * (DSTRN(2) + DSTRN(3))
STRESS(6) = POISSONS_RATIO * YOUNG_MODULUS * (DSTRN(1) + DSTRN(3))

! Update material state variables (empty in this case)
DDSDDE(:) = 0.0

RETURN
END SUBROUTINE UMAT

Block Description:

1. Lines 1-2: Include necessary files (replace USER_MATERIAL_PROP.INC with your actual property definition file).
2. Lines 4-5: Define stress and strain tensors.
3. Lines 7-8: Allocate state variables and material properties arrays. Note (:) allows for variable size based on user definition in NSV.
4. Lines 10-11: Access Young’s modulus and Poisson’s ratio from material properties.
5. Line 13: Set the number of state variables (0 for linear elasticity).
6. Line 15: Calculate bulk modulus (derived property based on other properties).
7. Lines 17-22: Implement stress update logic using constitutive equations for linear elasticity.
8. Lines 24-25: As there are no state variables, set their update to zero.

Note:

• This is a basic example. You’ll need to modify it for more complex material behavior.
• Remember to define the material properties (Young’s modulus and Poisson’s ratio) in your input file for Abaqus to pass them to the UMAT subroutine.
• Refer to the Abaqus documentation for detailed information on UMAT arguments and functionalities.
• Moreover, you can get another example and have access to the software files below.

10. Conclusion

This article aimed to guide users through the process of writing and using UMAT and VUMAT subroutines in Abaqus. These tools are essential for developing custom material models that address the limitations of predefined Abaqus material libraries. By providing practical insights, the article ensures a foundational understanding of these advanced subroutine capabilities.

We explored the key steps involved in writing UMAT and VUMAT, including defining theoretical material models, understanding Abaqus parameters, and developing Fortran code. The article also discussed implementing these subroutines in Abaqus, debugging, verifying results to ensure accuracy and reliability in simulations, and the difference between UMAT and VUMAT. Throughout, examples highlighted both static and dynamic applications, showcasing when to use UMAT or VUMAT based on the analysis type.

In summary, mastering UMAT and VUMAT enables engineers to tackle specialized material modeling challenges effectively. By following the structured approach outlined here, you can confidently implement these subroutines and enhance your simulations. As discussed in the introduction, the choice between UMAT and VUMAT depends on your analysis requirements, making these tools versatile and invaluable in computational.

Get the example files of Elasticity and TSAI failure criterion for free:

Users ask these questions

Now, let’s see some questions users asked us regarding the UMAT subroutine. We answered them and suggested relative articles and products.

I. Writing UMAT subroutine

Q: Salutations to all.
I’m new to UMAT in Abaqus and would like to construct UMAT for “shell” elements for an anisotropic and isotropic material. Can anyone recommend any books, websites, or other sources of information that could be helpful?
Many thanks.

A: Hello,

If you have just started to write the UMAT subroutine, I recommend reading the article which I share its link below:

“Start Writing Your 1st UMAT Abaqus”

Also, you can watch this YouTube video that teaches you how to write a UMAT subroutine with a very simple example:

If your model is orthotropic, and shell element or continuum shell or anything than 3D continuum solid, check the link below:

Simulation of Unidirectional Composite Damage in ABAQUS

for 3D continuum solid element and fatigue analysis, check the following links:

3D continuum Abaqus HASHIN progressive Damage for composite materials (VUMAT Subroutine)

Composite Fatigue Simulation with UMAT Subroutine in ABAQUS (unidirectional)

Best regards.

II. Zero stress & strain in UMAT subroutine

Q: Hi All,
I am simulating the development of oxide layers on metal and I have referred to the following paper:

10. Wang, J.-L. Grosseau-Poussard, B. Panicaud, and C. Labergère, “Finite Element Analysis of Stress Evolution During the High-Temperature Oxidation of Ni30cr+ Cr2O3 Systems,” Journal of Alloys and Compounds, vol. 904, p. 164094, May 2022, doi: 10.1016/j.jallcom.2022.164094.

The model is a 20x20x20-millimeter 3-D cube with a metal coating that extended up to 18 millimeters. The air layer that supports the formation of the oxide layer is then 18 to 20 m thick. The system starts at a temperature of 25 ° c., and after 30 minutes it has reached a temperature of 900 ° c. The system is then maintained at 900oC for 10 hours, after which the temperature has dropped to 25oC. The oxide layer has only grown in accordance with an exponential function during the isothermal step.

The ABAQUS User Material (UMAT) function was used for this simulation. In addition, the first author informed me (over a few email conversations) that he utilized the air layer’s Young’s modulus low value and set STRESS and STRAIN zero to avoid having an impact on the system’s behavior inside each increment. The air layer’s primary purpose, like that of the paper, is to create room for the oxide layer to grow.
How can I use a UMAT to set STRESS and STRAIN to zero in every increment?

A: Hello,

In the UMAT subroutine, you can set the stress and strain to zero, but you may encounter the convergence issue. In such cases, the stress and strain will usually be set to a value near zero to avoid convergence issues. Usually, the value is one-hundredth of the stress applied to the model. For example, the stress is applied to the steel in the MPa scale, so you should set the stress to 2 or 5.

If you have a problem writing the UMAT subroutine, I recommend referring to the links below.

Start Writing Your 1st UMAT Abaqus

https://www.youtube.com/watch?v=96sfwnvLHkA

UMAT Subroutine (VUMAT Subroutine) introduction

Best regards.

III. Material orientation

Q: I’m working on an ABAQUS model that requires material orientation to change over time. As far as I’m aware, ABAQUS orientation can only be spatially different when using the *ORIENT subroutine. But I’m curious if there are any other options for assigning an orientation that changes over time.

A: Hello,

Besides using the ORIENT subroutine, you can write the UMAT subroutine for your material and any conditions you want in there. If you want to use the UMAT subroutine, I recommend referring to this link:

UMAT Subroutine (VUMAT Subroutine) introduction

Best regards.

IV. UMAT and XFEM crack modeling

Q: I’m going to use XFEM crack to run a crystal plasticity model. USER MATERIAL describes the material properties. An error message came when the job was submitted: “Elastic property reference is missing for 39600 elements. The elements have been found in the ErrElemMissingElastic PropRef element set “.. This warning surprised me because elastic and plastic deformations were described in UMAT. However, the job cannot be successfully submitted.
Thank you for your time and consideration.

A: Hi,

This error could have two reasons:

The material you defined in the subroutine doesn’t match the geometry and the section you defined. For example, your model is solid, and the material properties you defined are for the shell model. the second reason is you may have assigned the wrong element type in the Mesh module. Check the simulation and see which one this is.

Also, I recommend checking the links below. They will help you write the UMAT subroutine and learn more about it. It’s worth a look.

Start Writing Your 1st UMAT Abaqus

https://www.youtube.com/watch?v=96sfwnvLHkA

Best regards.