<!-- source-page: 301 -->

# NOEL

Element number.

# NPT

Integration point number.

# LAYER

Layer number (for composite shells and layered solids).

# KSPT

Section point number within the current layer.

# JSTEP(1)

Step number.

# JSTEP(2)

Procedure type key (see “Results file output format,” Section 5.1.2 of the Abaqus Analysis User’s Guide).

# JSTEP(3)

1 if NLGEOM=YES for the current step; 0 otherwise.

# JSTEP(4)

1 if current step is a linear perturbation procedure; 0 otherwise.

# KINC

Increment number.

# Example: Using more than one user-defined mechanical material model

To use more than one user-defined mechanical material model, the variable CMNAME can be tested for different material names inside user subroutine UMAT as illustrated below:

```txt
IF (CMNAME(1:4) .EQ. 'MAT1') THEN
    CALL UMAT_MAT1(argument_list)
ELSE IF(CMNAME(1:4) .EQ. 'MAT2') THEN
    CALL UMAT_MAT2(argument_list)
END IF 
```

UMAT\_MAT1 and UMAT\_MAT2 are the actual user material subroutines containing the constitutive material models for each material MAT1 and MAT2, respectively. Subroutine UMAT merely acts as a directory here. The argument list may be the same as that used in subroutine UMAT.

<!-- source-page: 302 -->

As a simple example of the coding of user subroutine UMAT, consider the linear, viscoelastic model shown in Figure 1.1.44–1. Although this is not a very useful model for real materials, it serves to illustrate how to code the routine.

The behavior of the one-dimensional model shown in the figure is

$$
\sigma + \frac {\mu_ {1}}{(E _ {1} + E _ {2})} \dot {\sigma} = \frac {\mu_ {1}}{(1 + E _ {1} / E _ {2})} \dot {\varepsilon} + \frac {1}{(1 / E _ {1} + 1 / E _ {2})} \varepsilon ,
$$

where $\dot { \sigma }$ and $\dot { \varepsilon }$ are the time rates of change of stress and strain. This can be generalized for small straining of an isotropic solid as

$$
\sigma_ {x x} + \tilde {\nu} \dot {\sigma} _ {x x} = \lambda \varepsilon_ {V} + 2 \mu \varepsilon_ {x x} + \tilde {\lambda} \dot {\varepsilon} _ {V} + 2 \tilde {\mu} \dot {\varepsilon} _ {x x}, \quad \mathrm{etc.},
$$

and

$$
\sigma_ {x y} + \tilde {\nu} \dot {\sigma} _ {x y} = \mu \gamma_ {x y} + \tilde {\mu} \dot {\gamma} _ {x y}, \quad \mathrm{etc.},
$$

where

$$
\varepsilon_ {V} = \varepsilon_ {x x} + \varepsilon_ {y y} + \varepsilon_ {z z},
$$

and $\tilde { \nu } , \lambda , \mu , \tilde { \lambda } ,$ , and $\tilde { \mu }$ are material constants ( and $\mu$ are the Lamé constants).

A simple, stable integration operator for this equation is the central difference operator:

$$
\dot {f} _ {t + \frac {1}{2} \Delta t} = \frac {\Delta f}{\Delta t},
$$

$$
f _ {t + \frac {1}{2} \Delta t} = f _ {t} + \frac {\Delta f}{2},
$$

where $f \mathrm { i }$ is some function, $f _ { t }$ is its value at the beginning of the increment, $\Delta f$ is the change in the function over the increment, and $\Delta t$ is the time increment.

Applying this to the rate constitutive equations above gives

$$
(\frac {\Delta t}{2} + \tilde {\nu}) \Delta \sigma_ {x x} = (\Delta t \frac {\lambda}{2} + \tilde {\lambda}) \Delta \varepsilon_ {V} + (\Delta t \mu + 2 \tilde {\mu}) \Delta \varepsilon_ {x x} + \Delta t (\lambda \varepsilon_ {V} + 2 \mu \varepsilon_ {x x} - \sigma_ {x x}) _ {t}, \quad \mathrm{etc.,}
$$

and

$$
(\frac {\Delta t}{2} + \tilde {\nu}) \Delta \sigma_ {x y} = (\Delta t \frac {\mu}{2} + \tilde {\mu}) \Delta \gamma_ {x y} + \Delta t (\mu \gamma_ {x y} - \sigma_ {x y}) _ {t}, \quad \mathrm{etc.},
$$

so that the Jacobian matrix has the terms

<!-- source-page: 303 -->

![](images/page-303_26d520c0d5ad043c85fe843b76bda61a030fba18d68611d2dc64a52188ccef5e.jpg)

<details>
<summary>text_image</summary>

σ
E₂
μ₁
E₁
ε
σ
</details>

Figure 1.1.44–1 Simple linear viscoelastic model.

$$
\frac {\partial \Delta \sigma_ {x x}}{\partial \Delta \varepsilon_ {x x}} = \frac {1}{(\frac {\Delta t}{2} + \tilde {\nu})} [ \Delta t (\frac {\lambda}{2} + \mu) + \tilde {\lambda} + 2 \tilde {\mu} ],
$$

$$
\frac {\partial \Delta \sigma_ {x x}}{\partial \Delta \varepsilon_ {y y}} = \frac {1}{(\frac {\Delta t}{2} + \tilde {\nu})} [ \Delta t \frac {\lambda}{2} + \tilde {\lambda} ],
$$

and

$$
\frac {\partial \Delta \sigma_ {x y}}{\partial \Delta \gamma_ {x y}} = \frac {1}{(\frac {\Delta t}{2} + \tilde {\nu})} [ \Delta t \frac {\mu}{2} + \tilde {\mu} ].
$$

The total change in specific energy in an increment for this material is

<!-- source-page: 304 -->

$$
(\sigma_ {i j} + \frac {1}{2} \Delta \sigma_ {i j}) \Delta \varepsilon_ {i j},
$$

while the change in specific elastic strain energy is

$$
(\varepsilon_ {i j} + \frac {1}{2} \Delta \varepsilon_ {i j}) D _ {i j k l} \Delta \varepsilon_ {k l},
$$

where D is the elasticity matrix:

$$
\left[ \begin{array}{c c c c c c} \lambda + 2 \mu & \lambda & \lambda & 0 & 0 & 0 \\ \lambda & \lambda + 2 \mu & \lambda & 0 & 0 & 0 \\ \lambda & \lambda & \lambda + 2 \mu & 0 & 0 & 0 \\ 0 & 0 & 0 & \mu & 0 & 0 \\ 0 & 0 & 0 & 0 & \mu & 0 \\ 0 & 0 & 0 & 0 & 0 & \mu \end{array} \right].
$$

No state variables are needed for this material, so the allocation of space for them is not necessary. In a more realistic case a set of parallel models of this type might be used, and the stress components in each model might be stored as state variables.

For our simple case a user material definition can be used to read in the five constants in the order $\lambda , \mu , { \tilde { \lambda } } , { \tilde { \mu } } ,$ and so that

$$
\text { PROPS } (1) = \lambda ,
$$

$$
\text { PROPS } (2) = \mu ,
$$

$$
\operatorname{PROPS} (3) = \tilde {\lambda},
$$

$$
\mathrm{PROPS} (4) = \tilde {\mu},
$$

$$
\mathrm{PROPS} (5) = \tilde {\nu}.
$$

The routine can then be coded as follows:
```csv
SUBROUTINE UMAT(STRESS,STATEV,DDSDDE,SSE,SPD,SCD,
1 RPL,DDSDDT,DRPLDE,DRPLDT,
2 STRAN,DSTRAN,TIME,DTIME,TEMP,DTEMP,PREDEF,DPRED,CMNAME,
3 NDI,NSHR,NTENS,NSTATV,PROPS,NPROPS,COORDS,DROT,PNEWDT,
4 CELENT,DFGRD0,DFGRD1,NOEL,NPT,LAYER,KSPT,JSTEP,KINC)
```

C

INCLUDE 'ABA\_PARAM.INC'

<!-- source-page: 305 -->

```csv
C CHARACTER*80 CMNAME
DIMENSION STRESS(NTENS),STATEV(NSTATV),
1 DDSDDE(NTENS,NTENS),
2 DDSDDT(NTENS),DRPLDE(NTENS),
3 STRAN(NTENS),DSTRAN(NTENS),TIME(2),PREDEF(1),DPRED(1),
4 PROPS(NPROPS),COORDS(3),DROT(3,3),DFGRD0(3,3),DFGRD1(3,3),
5 JSTEP(4)
DIMENSION DSTRES(6),D(3,3)

C EVALUATE NEW STRESS TENSOR
C
EV = 0.
DEV = 0.
DO K1=1,NDI
EV = EV + STRAN(K1)
DEV = DEV + DSTRAN(K1)
END DO
C
TERM1 = .5*DTIME + PROPS(5)
TERM1I = 1./TERM1
TERM2 = (.5*DTIME*PROPS(1)+PROPS(3))*TERM1I*DEV
TERM3 = (DTIME*PROPS(2)+2.*PROPS(4))*TERM1I
C
DO K1=1,NDI
DSTRES(K1) = TERM2+TERM3*DSTRAN(K1)
1 +DTIME*TERM1I*(PROPS(1)*EV
2 +2.*PROPS(2)*STRAN(K1)-STRESS(K1))
STRESS(K1) = STRESS(K1) + DSTRES(K1)
END DO
C
TERM2 = (.5*DTIME*PROPS(2) + PROPS(4))*TERM1I
I1 = NDI
DO K1=1,NSHR
I1 = I1+1
DSTRES(I1) = TERM2*DSTRAN(I1)+
1 DTIME*TERM1I*(PROPS(2)*STRAN(I1)-STRESS(I1))
STRESS(I1) = STRESS(I1)+DSTRES(I1)
END DO
C
CREATE NEW JACOBIAN
C 
```

<!-- source-page: 306 -->

```asm
TERM2 = (DTIME*(.5*PROPS(1)+PROPS(2))+PROPS(3)+1 2.*PROPS(4))*TERM1I
TERM3 = (.5*DTIME*PROPS(1)+PROPS(3))*TERM1I
DO K1=1,NTENS
DO K2=1,NTENS
DDSDDE(K2,K1) = 0.
END DO
END DO
C
DO K1=1,NDI
DDSDDE(K1,K1) = TERM2
END DO
C
DO K1=2,NDI
N2 = K1-1
DO K2=1,N2
DDSDDE(K2,K1) = TERM3
DDSDDE(K1,K2) = TERM3
END DO
END DO
TERM2 = (.5*DTIME*PROPS(2)+PROPS(4))*TERM1I
I1 = NDI
DO K1=1,NSHR
I1 = I1+1
DDSDDE(I1,I1) = TERM2
END DO
C
C TOTAL CHANGE IN SPECIFIC ENERGY
C
TDE = 0.
DO K1=1,NTENS
TDE = TDE + (STRESS(K1)-.5*DSTRES(K1))*DSTRAN(K1)
END DO
C
C CHANGE IN SPECIFIC ELASTIC STRAIN ENERGY
C
TERM1 = PROPS(1) + 2.*PROPS(2)
DO K1=1,NDI
D(K1,K1) = TERM1
END DO
DO K1=2,NDI
N2 = K1-1 
```

<!-- source-page: 307 -->

```txt
DO K2=1,N2
    D(K1,K2) = PROPS(1)
    D(K2,K1) = PROPS(1)
END DO
END DO
DEE = 0.
DO K1=1,NDI
    TERM1 = 0.
    TERM2 = 0.
    DO K2=1,NDI
    TERM1 = TERM1 + D(K1,K2)*STRAN(K2)
    TERM2 = TERM2 + D(K1,K2)*DSTRAN(K2)
END DO
DEE = DEE + (TERM1+.5*TERM2)*DSTRAN(K1)
END DO
I1 = NDI
DO K1=1,NSHR
    I1 = I1+1
    DEE = DEE + PROPS(2)*(STRAN(I1).5*DSTRAN(I1))*DSTRAN(I1)
END DO
SSE = SSE + DEE
SCD = SCD + TDE - DEE
RETURN
END 
```

<!-- source-page: 308 -->

<!-- source-page: 309 -->

# 1.1.45 UMATHT: User subroutine to define a material’s thermal behavior.

# Product: Abaqus/Standard

WARNING: The use of this subroutine generally requires considerable expertise. You are cautioned that the implementation of any realistic thermal model requires significant development and testing. Initial testing on models with few elements under a variety of boundary conditions is strongly recommended.

# References

• “User-defined thermal material behavior,” Section 26.7.2 of the Abaqus Analysis User’s Guide   
• \*USER MATERIAL   
• “Freezing of a square solid: the two-dimensional Stefan problem,” Section 1.6.2 of the Abaqus Benchmarks Guide   
• “UMATHT,” Section 4.1.22 of the Abaqus Verification Guide

# Overview

# User subroutine UMATHT:

• can be used to define the thermal constitutive behavior of the material as well as internal heat generation during heat transfer processes;   
• will be called at all material calculation points of elements for which the material definition includes a user-defined thermal material behavior;   
• can be used with the procedures discussed in “Heat transfer analysis procedures: overview,” Section 6.5.1 of the Abaqus Analysis User’s Guide;   
• can use solution-dependent state variables;   
• must define the internal energy per unit mass and its variation with respect to temperature and to spatial gradients of temperature;   
• must define the heat flux vector and its variation with respect to temperature and to gradients of temperature;   
• must update the solution-dependent state variables to their values at the end of the increment;   
• can be used in conjunction with user subroutine USDFLD to redefine any field variables before they are passed in; and   
• is described further in “User-defined thermal material behavior,” Section 26.7.2 of the Abaqus Analysis User’s Guide.

<!-- source-page: 310 -->

# Use of subroutine UMATHT with coupled temperature-displacement and coupled thermal-electrical-structural elements

User subroutine UMATHT should be used only with reduced-integration or modified coupled temperaturedisplacement and coupled thermal-electrical-structural elements if the mechanical and thermal fields are not coupled through plastic dissipation. No such restriction exists with fully integrated coupled temperature-displacement and coupled thermal-electrical-structural elements.

User subroutine interface   
```fortran
SUBROUTINE UMATHT(U, DUDT, DUDG, FLUX, DFDT, DFDG,
    1 STATEV, TEMP, DTEMP, DTEMDX, TIME, DTIME, PREDEF, DPRED,
    2 CMNAME, NTGRD, NSTATV, PROPS, NPROPS, COORDS, PNEWDT,
    3 NOEL, NPT, LAYER, KSPT, KSTEP, KINC)
C
INCLUDE 'ABA_PARAM.INC'
CHARACTER*80 CMNAME
DIMENSION DUDG(NTGRD), FLUX(NTGRD), DFDT(NTGRD),
1 DFDG(NTGRD, NTGRD), STATEV(NSTATV), DTEMDX(NTGRD),
2 TIME(2), PREDEF(1), DPRED(1), PROPS(NPROPS), COORDS(3)
user coding to define U, DUDT, DUDG, FLUX, DFDT, DFDG,
and possibly update STATEV, PNEWDT
RETURN
END 
```

# Variables to be defined

U

Internal thermal energy per unit mass, U, at the end of increment. This variable is passed in as the value at the start of the increment and must be updated to its value at the end of the increment.

DUDT

Variation of internal thermal energy per unit mass with respect to temperature, , evaluated at the end of the increment.
