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)

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 Course:

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), …
…………………………………………………………………………………………………………………………………………

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.

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 :

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.

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.

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:

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.

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: Abaqus tutorial video

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.

You can find the theory in any basic Continuum or Elasticity reference books. Lazier to refer to books? Take a look at Abaqus documentation (Linear elastic behavior: Defining orthotropic elasticity in plane stress).

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 first part of this Article as a PDF: Subscribe Now!

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

References:

Tutorial: Write a simple UMAT in ABAQUS

Umat tutorial

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.

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. UMAT subroutine??

Q: Hello. I’m about to start a research project on fault rupture in soil, and I found that there’s a UMAT for Abaqus that can accurately represent soil strain-softening post-peak. Is there anyone who can assist me in finding or writing one?
Thank you very much.

A: Hi,

we have a article that I share its link below. It can help you understand what the UMAT subroutine is and how you can write one: 

“Start Writing Your 1st UMAT Abaqus“

Also, we have a tutorial package for those who are beginners in the UMAT subroutine: “UMAT Subroutine (VUMAT Subroutine) introduction“.

II. ABAQUS and DAMASK

Q: Hello DAMASK and ABAQUS users,

I want to run dislocation density based crystal plasticity finite element analysis in ABAQUS using DAMASK CP codes. I am able to run the simulations on the small geometries (single crystal). When I change to poly crystal I am getting the error as “Analysis is being terminated from a user subroutine” but when I check the data I found the following error ┌─────────────────────────────────────────────────────────────────────┐ │ warning │ │ 35 │ ├─────────────────────────────────────────────────────────────────────┤ │ could not get $DAMASK_NUM_THREADS │ │ BEGIN: :END │ │ │ └─────────────────────────────────────────────────────────────────────┘

Has anyone come across the above error?Any suggestions to resolve this error?

Thanks.

A: Hello,

First of all, you need to know the language of both coding platforms (UMAT and DMASK), and they must be the same or at least know how to convert them to another.

Secondly, according to your error “Analysis is being terminated from a user subroutine,” I think you can use more information about the UMAT subroutine. So, refer to the links below. You might find them helpful:

Start Writing Your 1st UMAT Abaqus

Also, check this link:

UMAT Subroutine (VUMAT Subroutine) introduction

it may help you a lot.

Best wishes.

III. 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.

IV. 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.

V. UMAT subroutine in ABAQUS

Q: Hello,

I am a new user of Abaqus and its libaray UMAT. Since I need to perform some CPFEM simulations, I used Huangs’s UMAT code. I tried to execute the example input file and to replicate the copper case study reported in: “A USER-MATERIAL SUBROUTINE INCORPORATING SINGLE CRYSTAL PLASTICITY IN THE ABAQUS FINITE ELEMENT PROGRAM“. The simulation exits with an error when using the example input file due to numerical singularities and when I create my own input file I’m not able to obtain plastic strain and I only have elastic response for any displacement and pressure value. Something is wrong but I can not figure it out.

Has someone encountered this problem?

Does anyone have any idea what the problem might be?

Thanks in advance for your help.

A: Greetings,

I think your code might have some errors, and you need to recheck it. I can recommend you some packages that will help you in modeling the plasticity of isotropic materials and composite materials with the UMAT subroutine:

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

UMAT Subroutine (VUMAT Subroutine) introduction

https://www.youtube.com/watch?v=Go8entmePiQ

Advanced UMAT Subroutine (VUMAT Subroutine)