How To - user defined material models with LS-Dyna on Windows

v1.2 – Leon Kellner, leon.kellner@tuhh.de – last updated 10.2020

This work is licensed under the Creative Commons Public Domain Mark 1.0
License. To view a copy of this license, visit
http://creativecommons.org/publicdomain/mark/1.0/

Especially note that: Affirmer offers the Work as-is and makes no representations or warranties of any
kind concerning the Work, express, implied, statutory or otherwise, including without limitation
warranties of title, merchantability, fitness for a particular purpose, non-infringement, or the absence of
latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.

Please let me know if any of the information below is outdated or you would like to add something.

Please also note that I cannot help you with obtaining any of the below-mentioned software.

1. Workflow Windows
1.1. What you need
 A dyna version suitable for making UMATs: currently I’m using
ls-dyna_smp_d_R11_1_0_ifort2017vs2017_lib
 Visual Studio 2017 Community Version 15.9.27.
 Intel Fortran Compiler: I currently use Intel Parallel Studio XE 2017 with Intel
Fortran Compiler 17.0.
 Optional: LS-Run
 Please note that other versions or combinations of versions might also run. If you have
trouble finding the right combination of Compiler, Visual Studio etc., it is probably a good
idea to contact the LS-Dyna support.
1.2. Step by step
i. Unzip your dyna version to the file location where you want to run the calculations.
ii. Install Visual Studio. Other versions than the above-mentioned might not work (.e.g.
community, express, etc). During the installation you can select several additional
features. They are not necessary for the compilation of LS-Dyna.
iii. Install the Intel Fortran Compiler. During the installation process from the compiler, it
should be recognized that Visual Studio is already installed. If this is not the case, help can
be found here:
https://software.intel.com/content/www/us/en/develop/articles/troubleshooting-fortran-
integration-issues-with-visual-studio.html
iv. Now you are ready to compile your own executable file.
Open Start->All Programs->Intel Parallel Studio XE 2017-> Compiler 17.0 Update 8 for Intel
64 Visual Studio 2017 environment
 Change directory to the folder, where you unzipped the ls-dyna_smp package
-> cd C:\...\...\...
Make the executable:
-> nmake
v. Check if your freshly compiled executable is working:
Either use LS-Run (open the .k - keyfile in LS-PrePost > File > Run LS-DYNA), or the
manager.exe, make sure to choose the correct executable and keyfile. I recommend
starting with a basic keyfile without UMATs.
vi. If you want to run a keyfile with UMATs, modify dyn21.f with your UMAT. Compile again
(nmake). Run the simulation. From here on it’s rinse and repeat – every time you change
your UMAT in dyn21.f you have to compile a new executable.

1.3. Common problems and possible solutions

i. "program can't start because libiomp5md.dll is missing"
-> The missing dll file should be in:
C:\Program Files (x86)\Common Files\Intel\Shared Libraries\redist\intel64\compiler
If not, download the file and
-> copy paste the file into the folder, where the executable is compiled
-> OR change path variables (administrator rights required)
-> https://stackoverflow.com/questions/694351/setting-library-path-for-win32-console-
applications
-> https://msdn.microsoft.com/en-us/library/office/ee537574(v=office.14).aspx
ii. If the libiomp5md.dll error appears when starting a LS-Dyna simulation, it can also help
to simply copy the file to the folder where you also compile the LS-Dyna executable.
iii. LS-Run is not running in parallel although you set NCPU >= 1
Insert ncpu=X in Expression behind "$SOLVER" i=$INPUT
iv. Simulation stops without any warning.
This could be a license issue. Have a look at your message file in the calculation folder. It is
possible that you have to set the network license either in LS-Run under Settings or in “edit
system environment variables”.
LSTC_LICENSE = network
LSTC_LICENSE_SERVER = “your_license_server.com”
LSTC_MEMORY = auto

2. Material Modeling with LS-Dyna

You can find information on user defined material models in Appendix A of the Keywords manual from
LS-Dyna, some additional information can be found in [1].

2.1. User defined materials (scalar version)

UMATs are implemented in the dyn21.f file with any kind of text editor in FORTRAN 77 or FORTRAN 90,
depending on what kind of compiler you are using. Most of the LS-Dyna specific coding of material models
is explained in the original dyn21.f file in the material model 41.

Generally, the subroutine runs on integration point level. The most important inputs are the stresses of
the previous time step and the strain increments in the current time step. The routine expects an update
of the stresses to the current time step. The stresses and strains at the beginning and end of the routine,
respectively, are given as vectors, similar to Voigt Notation. Inside LS-Dyna, the notation is as follows. If
the stress tensor is
𝜎11 𝜎12 𝜎13
𝝈 = [𝜎12 𝜎22 𝜎23 ]
𝜎13 𝜎23 𝜎33

the stress vector is 𝜎 = [𝜎11 𝜎22 𝜎33 𝜎12 𝜎23 𝜎13 ]T. Therefore

c sig(1)=local x stress
c sig(2)=local y stress
c sig(3)=local z stress
c sig(4)=local xy stress
c sig(5)=local yz stress
c sig(6)=local zx stress

the same applies to the strain increment.

Other inputs are the material constants cm(1..n). You can set these values in the material model of your
keyfile and access them in the subroutine via cm(1..n). Additionally, you can use history values
hsv(1..n) to access parameters or values you calculated in the time steps before the current time step,
e.g. to calculate an accumulated damage value. The history variables should also be updated to the
current time step. Don’t change the included nlqparam file. Everything besides the history variables and
other objects the subroutine initializes by default is not accessible outside the subroutine and will possibly
be deleted or overwritten at the end of each time step.

Besides programming the UMAT routine you have to implement your material model in your key file. This
is done through the keycard “MAT_USER_DEFINED_MATERIAL_MODELS”.

RO is the density. MT is the number of the material model in the dyn21.f file. LMC is the length of the
material constants array, NHV the number of history variables. The material constants are set in a matrix
with 8 columns (P1 – P8) and an arbitrary number of rows. However, they are accessed as a vector,
counting from 1 to n, e.g. the material constant set in the second row of the matrix in column P8 is
accessed as cm(16). You always have to set at least a bulk modulus as well as a shear modulus in the
material constants array and give their position in the cm(1..n) array under IBULK and IG.

2.2. User defined materials (vectorized version)

Vectorized material subroutines follow the same principles as the scalar versions, except that the variables
are accessed a little differently. A loop over all integration points in the block of length nlq is required.

do i = lft,llt
…
enddo

Within that loop, all variables are additionally accessed through the iteration variable i. For example, if
you use a Boolean flag ifail for failure or no failure of an integration point, this simply changes to
ifail(i). Likewise, stresses are accessed via sigX(i) with X=1 … 6.
 2.3. User defined cohesive models

User defined cohesive models follow similar principles as the user defined materials. They can also be
coded in scalar and vectorized versions. The user defined cohesive subroutine receives the difference of
displacements and velocities, respectively, of the upper and lower surface of the cohesive element. As
output, tractions and an upper bound for element stiffness is expected. See also Appendix R of the LS-
Dyna manual. They are edited in the dyn21b.f file.

Hence, the key inputs are the separations dx(i, 1 … 3) and the minimal output comprises the tractions
in three directions fc(i, 1 … 3) and the maximum stiffness for the time step calculation ek(i). Again,
vectorized through the iteration variable i.

You can find an example of a simple user defined cohesive model in the appendix below.

3. Examples of user defined cohesive models

3.1. Simple linear softening

Here is an example of a user defined cohesive model, which is based on [2]. The same material model is
available in the LS-Dyna material library, number 138.

c***********************************************************************
subroutine umat44c(idpart,cm,lft,llt,fc,dx,dxdt,aux,ek,
& ifail,dt1siz,crv,nnpcrv,nhxbwp,cma,maketan,dsave,ctmp,elsiz,
& reject,ip,nip,x) ! x (last argument) added to match umatc
subroutine call umat44c(idpart, ...., dm_x)
c
c User defined cohesive model. Last worked on 11.2018.
c Leon Kellner, leon.kellner@tuhh.de
c Source: Dávila, C.; Camanho, P. (2001): Decohesion Elements using Two and
c Three-Parameter Mixed Mode Criteria. In: American Helicopter Society
Conference.
c Williamsburg, VA, 2001.
include 'nlqparm'
include 'iounits.inc'

common/aux33loc/ix1(nlq),ix2(nlq),ix3(nlq),ix4(nlq),ix5(nlq),
& ix6(nlq),ix7(nlq),ix8(nlq),mxt(nlq)
C_TASKCOMMON (aux33loc)

c *** Variables --------------------------------------------------------

c *** Dyna variables / internal
logical ifail,maketan,reject

c declare arrays, * = assumed size array

dimension cm(*),fc(nlq,*),dx(nlq,*),dxdt(nlq,*),
& aux(nlq,*),ek(*),ifail(*),dt1siz(*),crv(lq1,2,*),
& nhxbwp(*),cma(*),dsave(nlq,6,*),ctmp(*),elsiz(*)
integer nnpcrv(*)
INTEGER8 idpart
real*8 x(3,*) ! added to access node id's
c *** user variables / external
real deltaII(nlq), deltaM(nlq) ! separation in tangential mode (mode
II)
real delta0(nlq) ! mixed mode onset of softening
real beta(nlq) ! mode mixity
beta=delta_I/delta_II=delta_3/delta_II
real delta0I, delta0II ! damage initiation displacement for
mode I and II
real deltaF(nlq) ! ultimate mixed mode displacement
(failure)
real dmg(nlq) ! damage parameter
real ePen ! penetration stiffness

c *** cm(*) material constants storage convention

c (1) = 0 density is per area
c = 1 density is per volume
c (2) number of integration points for element deletion
c = 0 no deletion
en=cm(3) ! EN - tangential stiffness (units of stress/length)
et=cm(4) ! ET - normal stiffness (units of stress/length)
t=cm(5) ! T - Peak traction in normal direction (stress
units)
s=cm(6) ! S - Peak traction in tangential direction (stress
units)
GIC=cm(7) ! GIC - Energy release rate for mode I (units of
stress*length)
GIIC=cm(8) ! GIIC - Energy release rate for mode II (units of
stress*length)
xmu=cm(9) ! XMU - Exponent of the mixed mode criteria
und=cm(10) ! UND - Ultimate displacement in the normal direction
utd=cm(11) ! UTD - Ultimate displacement in the tangential
direction
penalty=cm(12)! - stiffness multiplier, is ignored if <= 1

c *** history variables, aux(nlq,*)

c (1) ! deltaMaxM - maximum value of displacement
c (2) ! dmg - damage value
c (3) ! softening - true, if element is past peak stress and delta0
c (4) ! output - true, if integration point information is to be
written

c *** beginning of routine ---------------------------------------------

! input checks
! taken from LS-Dyna Material Models Manual 2017, MAT_138 description
if (((2*gic)/(t*t/en)) <=1) then
write (*,*) "Error: peak stress is past failure points!"
write (*,*) "Check input data for normal mode!"
stop
elseif (((2*giic)/(s*s/et)) <=1) then
write (*,*) "Error: peak stress is past failure points!"
write (*,*) "Check input data for tangential mode!"
stop
endif

if (penalty >= 1) then

ePen=penalty*max(en,et) ! penetration stiffness
 endif

delta0I=t/en ! damage initiation displacements (fixed values)

delta0II=s/et !
und=gic*2/t ! initial ultimate displacements
utd=giic*2/s

do i=lft,llt ! loop -----------------------------------------

deltaII(i)=sqrt(dx(i,1)*dx(i,1)+dx(i,2)*dx(i,2)) ! separation in
tangential mode (mode II)

! total mixed mode separation

if (dx(i,3) > 0) then ! only calculate mixed mode displacement
if normal displacement > 0
deltaM(i)=sqrt(deltaII(i)*deltaII(i)+dx(i,3)*dx(i,3))
else ! mixed mode displacement = tangential
displacement
deltaM(i)=deltaII(i)
endif

if ((dx(i,3) > 0) .and. (deltaII(i) > 0)) then ! mixed mode

displacement
beta(i)=deltaII(i)/dx(i,3) ! mode mixity
delta0(i)=delta0I*delta0II*sqrt( (1+beta(i)*beta(i))
1 /(delta0II*delta0II + beta(i)*beta(i)*delta0I*delta0I) ) !
mixed mode damage initiation displacement
deltaF(i)=((2+2*beta(i)*beta(i)) / delta0(i))
1 *( (en/GIC)**xmu + ((et*beta(i)*beta(i))/GIIC)**xmu )
2 **(-1/xmu) !
ultimate mixed mode displacement (failure)
elseif ((dx(i,3) > 0) .and. (deltaII(i) <= 0)) then ! only normal
displacement
delta0(i)=delta0I ! set delta0 to mode I delta0
deltaF(i)=und ! set deltaF to mode I deltaF
elseif ((dx(i,3) <= 0) .and. (deltaII(i) > 0)) then ! only
tangential displacement
delta0(i)=delta0II ! set delta0 to mode II
delta0
deltaF(i)=utd ! set deltaF to mode II
deltaF
else ! set initial values if all
displacement is zero
delta0(i)=max(delta0i, delta0ii)
deltaF(i)=max(und,utd)
endif

ifail(i)=deltaM(i) >= deltaF(i) ! failed if mixed mode

displacement > deltaF

! identify if peak stress has been reached

if (deltaM(i) >= delta0(i)) then
aux(i,3)=1 ! peak stress has been
reached / softening initiated
endif

aux(i,1)=max(deltaM(i), aux(i,1)) ! save maximum displacement value

 ! update cohesive forces / stresses and stiffness
! ***no damage / softening
if ((deltaM(i) <= delta0(i)) .and. (aux(i,2) <= 0)) then
fc(i,1)=et*dx(i,1) ! cohesive forces/stresses
through displacement and stiffness
fc(i,2)=et*dx(i,2)
fc(i,3)=en*dx(i,3)
ek(i)=max(et,en) ! max stiffness

! ***damage / softening, but not failed yet

elseif ((deltaM(i) > delta0(i) .or. (aux(i,2) > 0)) .and.
1 (.not. ifail(i))) then
aux(i,2)=(deltaF(i)/aux(i,1))*((aux(i,1)-delta0(i))
1 /(deltaF(i)-delta0(i))) ! update damage variable
fc(i,1)=et*(1-aux(i,2))*dx(i,1) ! cohesive forces/stresses with
updated stiffness
fc(i,2)=et*(1-aux(i,2))*dx(i,2)
fc(i,3)=en*(1-aux(i,2))*dx(i,3)
ek(i)=max(et*(1-aux(i,2)),en*(1-aux(i,2))) ! max stiffness

! ***complete damage / failure

elseif (ifail(i)) then
aux(i,2)=1
fc(i,1)=0
fc(i,2)=0
fc(i,3)=0
else
write (*,*) "Error: update cohesive forces"
write (*,*) "Else case should not be reachable!"
exit
endif

if ((dx(i,3) < 0) .and. (penalty >= 1)) then ! penetration

fc(i,3)=fc(i,3)+ePen*dx(i,3)
ek(i)=max(et*(1-aux(i,2)),en*(1-aux(i,2))) + ePen
endif

enddo ! end loop--------------------------------------

return
end

References
[1] T. Erhart, “An Overview of User Defined Interfaces in LS-DYNA,” in 8th European LS-Dyna
Conference, Strasbourg, France, 2011.
[2] C. Dávila and P. Camanho, “Decohesion Elements using Two and Three-Parameter Mixed Mode
Criteria,” in American Helicopter Society Conference, Williamsburg, VA, 2001.