Start Writing Your 1st UMAT Abaqus

UMAT Subroutine (VUMAT Subroutine) introduction

+160 min Video tutorial

-Standard and explicit solver

-workshops: hyperelastic Martials, Composites, Metal

-Language:  English

Advanced UMAT Subroutine (VUMAT Subroutine)

+140 min Video tutorial

-Standard and explicit solver

-damage in non-metallic materials such as composites and adhesives

-English subtitle

3D continuum HASHIN progressive Damage for composite

+160 min. Video tutorial

-Hashin damage initiation, gradual progressive damage based on the energy method

-usable for  static and dynamic problems

UMAT Subroutine in ABAQUS / Free Version

+60 min Video tutorial

-Basics of writing UMAT

– Workshop: Writing UMAT for Non-Isothermal Elasticity

– Language: English

Start writing your 1st Abaqus UMAT

Here our focus is on UMAT Abaqus or Abaqus UMAT subroutine, an advanced subroutine we use to include desired material behavior in simulations. However, the use of the UMAT subroutine which includes DDSDDE matrix is generally requires considerable expertise.

In this step-by-step guide, I just want to show how to get started with using/writing a UMAT in Abaqus by one of the simplest possible examples for this purpose, an elastic material.

First, I strongly recommend reading this article to get familiar with DDSDDE Abaqus UMAT and  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.

⭐⭐⭐Free Abaqus Course | ⏰10 hours Video  👩‍🎓+1000 Students   ♾️ Lifetime Access ✅ Module by Module Training                                  ✅ Standard/Explicit Analyses Tutorial ✅ Subroutines (UMAT) Training                    …           ✅ Python Scripting Lesson & Examples …………………………                 …………………………………………….. ……………………………………….   …………………………….Start Free Abaqus Course

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

⭐⭐⭐Free Abaqus Course | ⏰10 hours Video  👩‍🎓+1000 Students   ♾️ Lifetime Access ✅ Module by Module Training                                  ✅ Standard/Explicit Analyses Tutorial ✅ Subroutines (UMAT) Training                    …           ✅ Python Scripting Lesson & Examples …………………………                 ……………………………………………………….. …………………………..   …………………………….Start Free Abaqus Course

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: Start writing your 1st UMAT Abaqus

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