incrementalDriver

programmer’s manual

A.Niemunis

October 11, 2016

1 Introduction
incrementalDriver is a program for testing constitutive models. incrementalDriver enables element tests. It
deals with homogeneous fields only (i.e. no consolidation, no spatial changes of stress, strain and state variables, no
spatial change of material constants, no gradients of deformation are allowed for). incrementalDriver calls a material
routine (constitutive relations) with the syntax of the user material subroutine of AbaqusTM [1]. Given stress T, with
other internal state variables α (all at the beginning of an increment) and strain increment ∆, umat updates T and α
returning their values at the end of the increment. Moreover umat calculates a tangential stiffness matrix or a Jacobian
matrix E = ∂∆T/∂∆. The main task of incrementalDriver is to force umat to follow a prescribed loading path
formulated in strain or stress components. The complementary components are calculated and stored (in an output file)
together with the constitutive state variables. The main difficulty is to follow a prescribed stress path or a combined
stress/strain path (= loading). The problem arises from the fact that umat accepts only strain increment ∆ as input.
˘ the components of ∆ will be determined iteratively in a procedure similar to the
For a prescribed stress increment ∆T
equilibrium iteration (EI) in the FEM.
In order to use incrementalDriver you may omit ? sections. They provide additional information for programmers.

2 Notation
Matrix notation and a fixed orthogonal Cartesian coordinate system is used. The components of second rank tensors are
written as 6 × 1 column matrix, in particular
1 
1 = [1, 1, 1, 0, 0, 0]T , 0 = [0, 0, 0, 0, 0, 0]T 1
 1 
∆T = [∆T11 , ∆T22 , ∆T33 , ∆T12 , ∆T13 , ∆T23 ]T J=
 1


∆ = [∆11 , ∆22 , ∆33 , ∆γ12 , ∆γ13 , ∆γ23 ]T 1
1
The accent t̆, reads ”prescribed”, e.g. ∆T˘ i is a prescribed component of stress and ∆i is an unknown one of strain.
The upper index ti at a boldface variable denotes its value after the step number i.
The lower index tk at a boldface variable denotes its value after th equilibrium iteration step number k.

3 ? Flowchart
The following description of the algorithm of incrementalDriver is slightly simplified. It leaves aside transformed
variables and rigid rotations of the material. The flowchart is organized as follows:

1. Choose a umat.

2. Read the material constants

1
 3. Read an initial state = initial stress T0 , and an initial deformation 0 . Usually, 0 = 0 is the starting point of the
strain path. Internal state variables α0 must be initialized too. Print this initial state to the output file.
4. Call umat with a zero strain increment1 ∆ = 0 to get an estimate of the tangential stiffness E0 . In the case of a
stress or mixed control E0 will be needed to make the first guess about the strain increment ∆. The lower index
is the number of equilibrium iteration (EI).
5. Start an loop over load increments (values after the increment are denoted by the number of increment written as
the upper index, e.g. after first increment we have T1 = T0 + ∆T1 . The upper index (=number of increment) is
often omitted if the current increment is meant.
6. Read an increment from the prescribed stress/strain path:
• Mixed load increments may be prescribed, i.e. some components ∆ ˘ ij of the strain increment and the comple-
mentary components ∆T˘ kl (with ij 6= kl) of the stress increment are given.
• Transformed components may be used in prescribing the load increments. This means that linear combinations
˘ v with v = −tr  or linear combinations of stress components like ∆p
of strain components like ∆ ˘ with
p = −tr T may be prescribed. Very useful are increments of Roscoe’s invariants instead of the conventional
cartesian components.
7. Start the ”equilibrium” iteration (EI) within an increment. EI is necessary unless all load components are defor-
mations2 . The corrections cT are added to stress increments, e.g. ∆Tik = ∆Tik−1 + cT so that the prescribed stress
increments can be better approximated.
8. Make the first guess of the strain increment ∆1 using the initial jacobian E0 , i.e., solve ∆T1 = E.∆1 with some
unknown components in ∆1 and some in ∆T1 . The lower index k (at bold face symbol, say Tik ) tells the number
of EI and the upper index i tells the number of increment in step. If the upper index is omitted then the quantity
pertains to the current increment.
9. Call umat with ∆1 to get the approximated stress ∆T and a better estimation of the tangential stiffness E1
10. For prescribed stress components ∆T ˘ ij ( ddstress3 the approximation ∆Tij ( a_dstress 4 calculated with the
˘ i − ∆Ti (u_dstress5 . This error corresponds
current guess of the strain increment ∆ may have an error ui = ∆T
to the ”out of balance forces” in a true EI of a FE program and must be reduced (iteratively). We can have two
cases:
kuk > toler: EI is not finished. The error is considerable, so it must be reduced. For this purpose
(a) Calculate the corrected strain components where the stress components are prescribed using
∆2 = ∆1 + c with c = (E1 )−1 : u (1)
We must not modify the prescribed strain components. Hence, the above ∆2 must be overridden by setting
∆2 = ∆˘ wherever the strain control applies6 .
(b) Undo all updates (of stress, strain and state variables) performed by umat. For this purpose the stress and the
internal state variables from the beginning of the current increment must be memorized. incrementalDriver
stores them as r_stress and r_statev7 , respectively.
(c) Repeat the EI i.e. call umat with the improved ∆2 and with T and α from the beginning of the increment.
kuk < toler : EI is finished. The error kuk is acceptable
(a) Accept the updates done by umat (= do nothing).
(b) Write out everything that matters to the output file (to be plotted by another programs).
(c) Update the total strain, the time and continue with the next increment.
1 Ifyour umat crashes when called with ∆ = 0 and ∆t = 0 it will crash in Abaqus too.
2 No iterative process (no EI) is needed for fully strain-controlled loading (all components of ∆ are prescribed), because umat itself can
calculate the exact stress increments as the material response. If stress increments are prescribed as loads then strain increments must be
found iteratively by making a guess of ∆, calculating the corresponding increment ∆T, finding the desired stress correction, finding (linearly)
the corresponding correction in strain etc.
3 for ’desired delta stress’
4 for ’approximated delta stress’
5 for ’undesired delta stress’
6 The corrections c are called c_dstran in the program

7 r_ stands for ’remembered before increment’

2
4 ? How artificial deformation cycles are avoided
Undoing of inaccurate approximations ∆T and ∆α during EI means that umat is repeatedly given the same initial
stress and the same initial state in all iteration. Only strain increments are modified (updated according to ∆2 =
∆1 + c where c = (E1 )−1 : u) during the EI.
Such approach prevents an artificial (numerical) zigzag-like evolution of T and α in the EI. If stress and state increments
done in umat were kept by incrementalDriver after each EI, then the subsequent contributions cT and cα were
successively added to the total values of T and α. Such process is not exact because it is not physical. The sequence
of updates (with possible oscillations, unloadings, reloadings, zigzag trajectories) would be dictated by the convergence
procedure of EI rather than by physical phenomena. ”Numerical” oscillations of state variables might influence the
accuracy of the constitutive response and therefore should be avoided.

5 Rigid rotation

Symbolic and index notation of tensors are used in this section (not matrix notation)
The strain increments should be calculated from the Hencky strain with respect to the material axes

 = ln U, (2)

wherein U is the right stretch tensor from the polar decomposition F = R · U.

In a single *LinearLoad step we apply the total strain change  which is decomposed into ninc equal increments ∆. In
a 1D oedometric compression from the height H0 to Hn we would have
n
Hn X Hi
 = ln = ln (3)
H0 i=1
Hi−1

so it is evident that equal strain increments ln(Hi /Hi−1 ) = const do not imply equal increments of displacement, i.e.
Hi − Hi−1 6= const.
In some tests (for example simple shearing) we may wish to define a deformation path using the gradient of deformation F
rather than the strain  per step. For this purpose after the keyword *DeformationGradient all nine partial derivatives
F̆ = (∂x(tE )/∂x(tB )) of the position vector at the end (=time tE ) of the step with respect to the position vector at the
beginning (=time tB ) of the step must be specified in the following sequence

n o
F̆11 , F̆22 , F̆33 , F̆12 , F̆21 , F̆13 , F̆31 , F̆23 , F̆32 (4)

Note that F = 1 at the beginning (=time tB ) of the step. The displacement gradient F̆ − 1 is decomposed additively
into n = ninc equal (and sufficiently small) increments

˘ = 1 (F̆ − 1)
∆F (5)
n
This decomposition corresponds to Hi − Hi−1 = const in the 1D example discussed above so this decomposition is slightly
different than the one of *LinearLoad.
Let us denote ∆F = FE − FB = FE − 1 the difference of deformation gradients at the beginning (FB ) and at the end
(FE ) of the current increment. After Hughes and Winget [3] we calculate the following incremental approximations
 −1
1
∆L = ∆F · FB + ∆F and (6)
2
1 
D∆t = ∆ = ∆L + ∆LT (7)
2
1 
W∆t = ∆L − ∆LT (8)
2
 −1  
1 1
∆R = 1 − W∆t · 1 + W∆t (9)
2 2

3
The stress is updated using the equation

Ti+1 = Ti + ∆R · (Ti + ∆T) · ∆RT (10)

in which ∆T is the constitutive (co-rotational) stress increment calculated with ∆ in the subroutine umat. Analogously
we rotate the total strain tensor

i+1 = i + ∆R · ∆ · ∆RT (11)

Is the the original form better ?

Ti+1 = Ti + ∆R · Ti · ∆RT + ∆T (12)

After Rashid [5] the algorithm by Hughes and Winget [3] is only weakly objective (objective only for the special cases of
pure rotation or pure stretching but not for their combinations). For two input deformation increments that differ only
by a rotation a strongly objective stress update algorithm should guarantee that the output stress also differ only by a
rotation. Weak objectivity may cause artificial cumulative effects during cyclic shearing.

5.1 ? Material or spatial strain

Abaqus passes to umat the information about the total strain in rotated configuration, i.e. first rotated then stretched

 = ln V, (13)

and not in the material configuration  = ln U (first stretched and then rotated). For most geotechnical models it should
not be of importance because strain should not be treated as a state variable (the initial value indeterminable). In some
cases, however, we do need  = ln U, for example in order to evaluate a multiaxial strain amplitude during out-of-phase
cycles.
The definition of  = ln V makes it impossible to recognize rigid rotation from the deformation with the principal
axes rotation. The following example illustrates the problem. Suppose, the material was first uniaxially stretched with
F = U = diag(λ, 1, 1) = const (uniformly with λ 6= 1). Let us observe V during a subsequent rigid rotated with R(t).
Using a time-like parameter t and the abbreviations c = cos(ω̇t), s = sin(ω̇t) we may consider a rigid rotation about the
x3 axis:
" #
c −s 0 cλ −s 0
 
R= s c 0 and hence F = R · U = sλ c 0 (14)
0 0 1 0 0 1

The left stretch tensor obtained from F = V · R as V = F · RT = R · U · RT in the matrix form

" 2 #
c λ + s2 −cs + csλ 0
V = −cs + csλ c2 + λs2 0 (15)
0 0 1
Despite the rigid rotation the components of V oscillate.
why do they use the spatial strain in Abaqus ?

6 ? Solving a mixed problem

One may define a loading path prescribing several components of strain inclrements ∆ ˘ j and several complementary
˘
components of stress increments ∆Ti with i 6= j. A geotechnical example of mixed control is an oedometric test with the
prescribed axial stress and the prescribed zero radial strain.
incrementalDriver uses a routine usolver( ) to solves a system of linear equations y = E.x in which 6 × 6 stiffness
matrix E may be unsymmetric. The unknown components may lie on both sides of the equation. Six unknowns are
partly components ∆i of strain increments and partly components ∆Tj of stress increment. The prescribed components
˘ j and ∆T
∆ ˘ i have the complementary indices i 6= j. Geotechnical materials are often nonlinear and the stress increment
returned by umat is not a linearly related to the strain increment ∆T 6= E.∆. Therefore an iterative correction of the

4
unknown components is necessary. Corrections to ∆Tj are calculated directly by umat but correction to ∆i must be
˘ i − ∆T k is
found iteratively using the given Jacobian matrix. For this purpose a so-called undesired stress increment ∆T i
˘
calculated where the components ∆Ti are given. The Remaining values ∆Tj will be ignored by solver. The old increment
∆Tk is taken from the latest iteration (calculated with ∆k ). The correction to the strain increment
˘ − ∆Tk )
c = E−1 .(∆T with ∆k+1 = ∆k + c (16)

is added to the unknown components of the strain increment only. Components j with prescribed strain increments ∆˘ j

have cj = 0, of course. Using well programmed umats this Newton iteration should converge very fast. Our linear solver
usolver can deal with unknowns lying on both sides of equation (16)1 . The zero-one column matrix ifstress points to
components with the prescribed stress increment.
The formal parameters of usolver are
usolver(ddsdde,c_dstran,u_dstress,ifstress,ntens)
wherein
ddsdde = stiffness E;
c_dstran = correction to strain increment c ;
u_dstress = undesired stress ∆T ˘ i − ∆Ti (with zeros where strain components are prescribed );
ifstress = a list of 6 flags set to 1 or 0 if the stress or strain component is prescribed, respectively;
ntens = 6 number of equations.
The algorithm used in usolver has been described in [2].

7 ? Solving a perturbation problem

One may wish to examine in detail the material response by superposing a given state (T, e, α) with load increments in
different directions. Usually we apply strain increments of identical length but different directions. The resulting stress
responses form a so-called response envelope (or response polar) in the stress space. Conversely, one may also apply
unit stress perturbations and examine the material response in strain space. This can also be done experimentally, cf.
Lewin [4] or Royis and Doanh [6]. In order to produce the response polars, incrementalDriver must undo the updates
done by umat after each increment. In the case of stress probes we must complete the EI first (undoing the temporary
end-states from inaccurate iterations), then record the accepted end-state and finally remove this state from the material
memory to perform a stress probe in a different direction8 .
The strain or stress perturbations are calculated within a special mode of execution initiated by the keywords *PerturbationsS
or *PerturbationsE in the test.inp input file. They generate stress probes or strain probes, respectively.
Having evoked perturbation as a separate step in test.inp file, information about the number of probes number of
iterations and the time increment (for rate dependent models) must be provided. The next keyword, (usually *Rendulic
or *RoscoeIsomorph) should define transformed variables and the size R of the probes must be given. For example,
*PerturbationsE with *RoscoeIsomorph means that different strain probes of identical size are applied such that
q
˘ P )2 + (∆
(∆ ˘ Q )2 = R (17)

The size R is stored in deltaLoad(1) in the program.

8 Working with linearly transformed components

In some cases it is convenient to describe the stress/strain path in terms of transformed strain rate or stress increments.
8 Alternatively one could perform a series of small linear cycles in various directions each consisting of two strain increments with opposite

sense. However, such cycles do not reproduce the perturbation exactly because of small residual effects which may remain in the state variables
after each cycle.

5
8.1 ? Roscoe’s variables
The most popular transformed components are known as Roscoe’s variables:

p = −(T1 + T2 + T3 )/3 and q = −T1 + (T2 + T3 )/2 with (18)

2 1
v = −(1 + 2 + 3 ) and q = − 1 + (2 + 3 ) (19)
3 3
defined with principal stresses and strains for axially symmetric states. Generally, we admit any linear combination of
strain rate components to be a transformed strain rate, and analogously for the transformed stress rate. No combinations
of components of stress- and strain rates are allowed.
The definition of p and q reflects the manner in which a triaxial test is actually controlled. In a conventional triaxial test
(with the cell pressure acting also on the the upper end plate) we prescribe p and q rather than T1 and T2 = T3 .
In an undrained triaxial compression test of a fully saturated soil sample we may prescribe vertical and lateral pressures
(the components of the total stress Ttot ,) but the pore pressure is usually a part of the material response and therefore
the effective stress T cannot be directly controlled. Assuming incompressibility of water we control the volumetric strain
(v = const) and the difference q = −(T1 − T2 ) = −(T1tot − T2tot ) which is the deviatoric effective stress (= deviatoric total
stress). The material response is observed through the complementary variables p (after subtraction of pore pressure)
and q . We cannot treat the effective stress components as prescribed because they are affected by the build-up of pore
water pressure, i.e. by a part of the material response which we do not control. In this case choosing the transformed
variables together with a mixed control seems quite natural for numerical simulation.
A transformed stress rate measure9 can be written as ∆t = M.∆T, wherein M is a non-singular matrix of constant
coefficients ( ’the regular linear substitution’ or ’linear transformation’ ). The corresponding strain rate follows from the
postulated conservation of second-order work ∆TT .∆ = ∆tT .∆e. Hence we have

∆t = M.∆T ∆e = M−T .∆ ∆T = M−1 .∆t ∆ = MT .∆e (20)

Matrix M the non-singular not necessarily symmetric nor orthogonal. Linear constitutive relation between ∆t and ∆e is

∆t = Ē.∆e with Ē = M.L.MT , (21)

One says that Ē and E are congruent. Note that the components of ∆t and ∆e need not be invariant. In Section 8.2 we
demonstrate M for Roscoe’s invariants and in Section 8.3 we explain the equilibrium iteration for incrementally nonlinear
constitutive models under stress or mixed control.

8.2 Using Roscoe’s invariants in incrementalDriver

The Roscoe’s invariants as components of stress and strain can be evoked by the keyword *Roscoe in the input file
test.inp for incrementalDriver. The strain and stress components are

∆v −1 −1 −1 0 0 0
          
∆p  −1/3 −1/3 −1/3 0 0 0 ∆T ∆

 ∆T11  ∆11
 ∆q  −2/3 1/3 1/3 0 0 0  
      
 ∆q   −1 1/2 1/2 0 0 0  
     
   22 
  
  22 

∆z =
 0 −1 1 0 0 0 · ∆T33 and ∆z =
 0 −1/2 1/2 0 0 0  ∆33
· ∆γ (22)
 ∆T12    0 0 0 1 0 0 
 ∆T12   ∆γ12  0 0 0 1 0 0 

12 
 ∆T13   ∆T13  ∆γ13

0 0 0 0 1 0  ∆γ13 0 0 0 0 1 0

  
 
 
 
 
 

   
∆T23 0 0 0 0 0 1 ∆T23 ∆γ23 0 0 0 0 0 1 ∆γ23

or briefly ∆t = M.∆T and ∆e = M−T . ∆. A somewhat arbitrary stress component ∆z is introduced to insure the
one-to-one relation between ∆t and ∆T. The component ∆z of ∆e is the strain counterpart of ∆z. We may use them
to impose the axial symmetry of stress or strain by setting ∆z = 0 or ∆z = 0, respectively.

8.3 ? Equilibrium iteration with transformed variables

One may want to define loading prescribing some components of ∆e and some the complementary components of ∆t.
Analogously as in Section 6 we need to perform the equilibrium iteration due to nonlinearity ∆t 6= Ē.∆e. Iteratively we
˘ i − ∆tk calculated from components with prescribed the stress increments ∆t
try to diminish the undesired stress ui = ∆t ˘ i
i
9 This t should not to be mixed up with the traction (=stress vector).

6
 ˘ j are ignored
and with ∆tki from the latest iteration. As in Section 6, components uj corresponding to the prescribed ∆e
by the solver10 . The correction ce of the transformed strain increment is found from
˘ − ∆tk )
ce = Ē−1 .(∆t and ∆ek+1 = ∆ek + ce (23)
˘ j must
This correction pertains to the unprescribed transformed strain components only. The prescribed increments ∆e
e
not be corrected and hence cj = 0 should be considered in (23)1 .

8.4 Other transformed variables implemented in IncrementalDriver

The conventional set of components is used in incrementalDriver if the data describing the test path is preceded by the
keyword *Cartesian. Apart from *Roscoe two other sets of transformed components can used by incrementalDriver,
namely :
*RoscoeIsomorph with

∆t = [∆P, ∆Q, ∆Z, ∆T12 , ∆T13 , ∆T23 ]T ∆e = [∆P , ∆Q , ∆Z , ∆γ12 , ∆γ13 , ∆γ23 ]T (24)

and *Rendulic with

√ √
∆t = [∆σ1 , 2∆σ2 , ∆Z, ∆T12 , ∆T13 , ∆T23 ]T ∆e = [∆1 , 2∆2 , ∆Z , ∆γ12 , ∆γ13 , ∆γ23 ]T (25)

If these keywords appear before the test path data in the input file test.inp then incrementalDriver will use the
following linear transformation matrices:
 √ √ √   −1
−1/√3 −1/√3 −1/√3 0 0 0 √0 √0 0 0 0

 −2/ 6 1/ 6 1/ 6 0 0
√ √ 0  0 −1/√2 −1/√2 0 0 0 
MRosc =  or MRend =  0 −1/ 2 1/ 2 0 0 0 
 
0 −1/ 2 1/ 2 0 0 0 
(26)
0 0 0 1 0 0

 0 0 0 1 0 0 
0 0 0 0 1 0
 
0 0 0 0 1 0
0 0 0 0 0 1 0 0 0 0 0 1

respectively. Both matrices are orthogonal so M−T = M. This is not true for the M matrix corresponding to *Roscoe.

8.5 ? Flowchart of a single step for transformed variables

In this flowchart the equilibrium iteration is explained in terms of transformed components. The term ”where” should
be understood as ”at the components for which”.
a. only in the first increment of a step: initialize stress T = T0 , strain  = 0 and state variables α = α0
call umat to calculate E for ∆ = 0 and ∆t = 0
b. read the type loading, choose M and MT and transform stiffness to Ē = M.E.MT
c. read increments of transformed components ∆t ˘ i and ∆e˘ j (distinguishing i 6= j from ifstress)
d. make the initial guess of the stress increment, e.g. ∆tk = 0
e. remember the end-stress Tr = T and the end-state αr = α from the latest increment
r_stress(:)= stress and r_statev(:)=statev(:)
f. enter the equilibrium iteration -loop numbered with k

˘ i − ∆tk for components i with prescribed stress, wherein ∆tk is

g. calculate the undesired (out-of-balance) stress ui = ∆t i
the stress increment the the latest iteration
˘
h. set ce = 0 where ∆e is prescribed and solve ce = Ē.(∆t−∆t k
) call USOLVER(ddsdde_bar,c_dstran,u_dstress,ifstress,ntens)
k+1 k e
i. correct the increment ∆e = ∆e + c where (ifstress == 1) dstran = dstran + c_dstran
j. convert the strain increment to cartesian form ∆ = MT .∆e dstran_Cart
k. call umat with the corrected ∆k+1 and with Tr , αr to update T and α and to get a new E
l. if iiter < maxiter: • improve the approximation of the stress inc ∆tk+1 = M.(T − Tr )
• undo the update of stress and state performed by umat T = Tr , α = αr
• repeat the EI with k := k + 1
10 One may pad uj them with zeroes

7
m. if iiter == maxiter: • add dstran_Cart(:) to 
• accept the update of stress Tk+1 and state αk+1 performed by umat
• reset the couter of iteration k := 1
n. use the most recent E and ∆t as the initial guess in the next increment

9 Preparing input for incrementalDriver

incrementalDriver reads three input files: parameters.inp, initialconditions.inp and test.inp. For all these
files the following rules apply
• No empty lines;
• No comment lines;
• The end-of-line comments are allowed but after 15 spaces;
• Integers in input must not have a decimal point;
• Strings in input must not have apostrophes. They must start from the first column (no preceding spaces). The asterisk
is the first character of each keyword. The capital letters are important in the keywords.
• Only spaces can be used as separators of data in a single line (no commas or semicolons)
The above filenames can be overridden by the parameters in the command line. The default values of the command-line
parameters are given in the following example:
incrementalDriver test=test.inp param=parameters.inp ini=initialconditions.inp verbose=true
If we set verbose=false no information about the currently calculated step and increment will be output to the screen.

9.1 Material constants

The material constants are read from the file parameters.inp. All should be input one item per line in the following
sequence
Remarks:
cmname The current material name cmname and the number of material constants nprops is followed by
nprops
props(1)
a list of constants props(1), props(2) .... The meaning of props depends on the internal
props(2) definitions in umat. Contrarily to the syntax of AbaqusTM just one material constant per line is
... read. The end-of-line comments after the data are allowed for. Note that the name of the material
props(nprops) cmname is character*80 so in this case the end-of-line comment should start from column 81 or
farther.

9.2 Initial conditions

The initial conditions are read from the file initialconditions.inp in the following sequence

ntens Remarks:
stress(1)
stress(2) 1. We always have ndi = 3 which means that the first three components stress(1),
... stress(2), stress(3) must be specified. They correspond to T11 , T22 , T33
stress(ntens)
nstatv
2. incrementalDriver is working internally with full six components so for ntens < 6 the
statev(1)
statev(2) initial values of the remaining components are just all set to zero.
...
statev(nstatv) 3. The components of stress are listed in the following sequence T11 , T22 , T33 , T12 , T13 , T23
4. Despite transformed variables used to define loading the initial stress is always defined with
the classical Cartesian components.
5. If the input is too short the remaining components of statev( ) will be padded with zeros.
In other words, if the end of the file initialconditions.inp is encountered by incremen-
talDriver after, say, statev(5) and nstatv > 5 then each of the values statev(6) ,
statev(7) . . . statev(nstatv) is set to zero.

8
9.3 Prescribing the test path
The strain/stress path is read from the file test.inp. In the first line the name of the output file (character(len=260)
must be given. If # is found in the first line then only the portion on the left-hand side of # is interpreted as the name of
the output file. The portion of the first line on the right-hand side of # is copied to the output file as a heading line.

outputFileName # optional heading copied to the outputFile

The output file name is obligatory but it can be overridden by a parameter in the command line, for example:
incrementalDriver out=output.out
The heading (if we define one beyond # in the test.inp) will not be affected by command line.
Further lines contain the description of steps. Similarly as in AbaqusT M the word ”step” means a sequence of similar
prescribed increments. The art of step is defined by a keyword preceded with an asterisk.

9.3.1 Proportional path

For proportional increments one may use *LinearLoad

∗LinearLoad
ninc maxiter deltaTime // number o f i n c r e m e n t s , max . number o f EI and t o t a l t i m e f o r t h e s t e p
∗Cartesian // other p o s s i b i l i t y are : ∗ R o s c o e , ∗ R o s c o e I s o m o r p h , ∗Rendulic
i f s t r e s s (1) deltaLoad (1) // 0/1 F l a g f o l l o w e d by an i n c r e m e n t o f s t r e s s o r s t r a i n
i f s t r e s s (2) deltaLoad (2)
...
i f s t r e s s (6) deltaLoad (6)

The components of ”load” pertain to the whole step i.e. depending on the flag ifstress(i) the i-th component is calcu-
lated as prescribed stress increment ddstress(i) = deltaLoad/ninc or strain increment dstran(i) = deltaLoad/ninc.
In the current version of the program there is no convergence criterion. The desired number maxiter of
equilibrium iterations is carried out irrespectively of convergence which may have already been achieved. After
the last equilibrium iteration the next load increment is applied irrespectively of whether the previous iteration
was successful (small out of balance stress) or not. Controlling stress components we should carefully examine if
the desired stress path was indeed applied to the material. One can prescribe an ”impossible” stress increment
(e.g. going outside the yield surface). In this case incrementalDriver will do its best to achieve the required
state but the calculation will not be interrupted if incrementalDriver fails. Insufficient accuracy within
the stress controlled regime may also be caused by too small number maxiter of iterations. The number of
equilibrium iterations should be increased for inaccurate Jacobian matrices in umat.f and for large increments.

9.3.2 Harmonic oscillation

A useful alternative, especially for cyclic loading, is a harmonic oscillation *CirculatingLoad with the syntax
∗CirculatingLoad
ninc m a x i t e r d e l t a T i m e // number o f i n c r . p e r c y c l e , max . number o f EI and t o t a l t i m e f o r t h e s t e p
∗Cartesian // here other p o s s i b i l i t i e s are : ∗ R o s c o e , ∗ R o s c o e I s o m o r p h , ∗Rendulic
i f s t r e s s ( 1 ) d e l t a L o a d C i r c ( 1 ) p h a s e 0 ( 1 ) d e l t a L o a d ( 1 ) // 1/0 F l a g , a m p l i t u d e , p h a s e and l i n e a r s t e p l o a d
i f s t r e s s ( 2 ) deltaLoadCirc ( 2 ) phase0 ( 2 ) deltaLoad ( 2 )
...
i f s t r e s s ( 6 ) deltaLoadCirc ( 6 ) phase0 ( 6 ) deltaLoad ( 6 )

Each stress or strain component consists of a harmonic portion superposed by a linear part (monotonic) portion. The
harmonic portion is described by the amplitude deltaLoadCirc(i) and by the initial phase phase0(i) The linear part
described by deltaLoad. The linear portion of each increment is constant over the step and it is calculated with

Bi = deltaLoad(i)/ninc (27)

The harmonic portion is varying with the step time t = deltaTime treated as a full period. This means that the total
increments of each component are calculated from
(0)
∆Li = ω̇∆tAi cos(ω̇t + ωi ) + Bi (28)

9
wherein ∆Li denotes either the increment of stress ddstress(i) or the increment of strain dstran(i), depending on the
value of ifstress(i) for the i-th component. Other variables are
ω̇ = wd = 2*Pi/deltaTime
∆t = dtime
Ai = deltaLoadCirc(i)
Bi =deltaLoad(i)/ninc
t = time(1) + dtime/2 ! step time in the middle of the increment
(0)
ωi =w0(i)= phase0(i)

9.3.3 ? On transformation matrices

Inventing new transformation matrices M we may simulate different kinds of laboratory tests. However the applicability
of this technique is limited. Consider an isobaric biaxial test under condition ∆T1 + ∆T2 + ∆T3 = 0 with ∆3 = 0 and
∆1 = −0.01. It turns out that a linear transformation matrix M for ∆t = M.∆T and ∆e = M−T .∆ cannot be
constructed for such loading. In this section we demonstrate the problem using principal components of strain and stress
only. A remedy is proposed in Section 9.3.4.
A description of our loading requires the transformed components of stress t1 = tr T, t2 =?, t3 =? and the transformed
components of strain e1 =?, e2 = 2 and e3 = 3 . Transformation matrix M should therefore have the form

=M = M−T
z" }| #{ ( ) z
" }| #{ " #
 p  f f f T1 
e1
 a =? b =? c =?  1  1 1 0 0
t2 = e2 2 −T −T −b/d a/d 0
? ? ? T2 , = 0 d =? 0 (M ) = (29)
t3 ? ? ? T3 e3 0 0 e =? 3 a −c/e 0 a/e

wherein (29)2 is the most general form of M−T . Its inverse11 has the form (29)3 which cannot be brought to the form
(29)1 needed for the prescription of stress increments. In order to circumvent this and similar problems we will extend
the mixed control algorithm using restrictions.

9.3.4 ? Imposing loading via restrictions

At first, we consider a linear material ∆T = E.∆. Suppose that all stress and strain increments are unknown so that
we have 6 constitutive equations and 12 unknowns. The additional 6 equations are called restrictions in Incremen-
talDriver. Restrictions allows for more flexibility than the transformation Matrix M. The additional equations are
assumed to have the general linear matrix form Mt · ∆T + Me · ∆ = m where the components of 6 × 6 matrices Mt and
Me are arbitrary state functions independent of increments. We have solve the system of 12 equations
(
∆T = E.∆
(30)
Mt · ∆T + Me · ∆ = m

with 12 unknown increments ∆T and ∆ The restrictions are linear with respect to ∆T and ∆. Only constant com-
ponents of Mt , Me and m have been implemented12 in IncrementalDriver. For the isobaric biaxial test from Section
9.3.3 the restrictions would be formulated as follows
= Mt = Me =m
z }| { ( z }| { (
)  ) z }| {

1 1 1 ∆T1 0 0 0 ∆1 0
0 0 0 · ∆T2 + 1 0 0 · ∆2 = −0.01 (31)
0 0 0 ∆T3 0 0 1 ∆3 0

In the test.inp file we can impose this loading in ninc = 100 increments with maxiter = 20 and within time deltaTime = 1
using the following description of the step *ObeyRestrictions. This example shows the natural manner of restricting
increments
∗ObeyRestrictions
100 20 1.0
sd1 + 1 . 0 ∗sd2 + sd 3 = 0 ! restriction 1 = isobaric condition
ed1 = −0.01 ! restriction 2

11 VerbMiT = {{a,b,c},{0,d,0},{0,0,e}}; Transpose[Inverse[MiT]] //MatrixForm

12 In general they could be functions of time, stress etc.

10
ed3 = 0 . 0 ! ....
ed4=0
ed5 = 0 . 0 d0
ed6 = −0 ! restriction 6

Note that parsing abilities of the IncrementalDriver are very limited. Here are some formal rules:
• The input line cannot be longer than 120 characters.
• No brackets (), no exponents ** or divisions / may appear.
• Each component sd1,sd2,sd3,sd4,sd5,sd6 of the stress increment and/or each component ed1,ed2,ed3,ed4,ed5,ed6
od strain increment may appear once on the left-hand side of the restriction, i.e. one cannot write sd1 + sd1 . Lower
case is obligatory.
• Each component constitutes a summand and can be preceded by a single factor, e.g. 9.0d-4*sd1 but not 3*3.0d-4*sd1
and not sd1*3.14. Summands without stress or strain components are not allowed, i.e. one cannot write sd1 + 1.0 + sd2 =
• As yet only numerical coefficients are allowed, not t*sd1
• If a factor precedes, the sign * for multiplication is obligatory.
• The summands are separated by + or -.
• The spaces are ignored but not inside numbers, of course.
• There must be just a single constant value in each restriction. It must appear on the right-hand side of the restriction
and can be preceded by -. No multiplication may appear on the right-hand side.
The end-of-line comments must begin with !. Exactly 6 lines with restrictions must be formulated without blank lines
between them.

9.3.5 ? Equilibrium iteration with restrictions

Most constitutive models of soil mechanics are nonlinear. Hence we must handle the discrepancy between the constitutive
stress increment f(∆) which is a nonlinear function of ∆ and the stress increment ∆T = E · ∆ obtained from the
∂f
linearized constitutive model, where E = . This discrepancy is removed in the course of the equilibrium iteration (EI).
∂
The EI can be coupled with restrictions. The algorithm is summarized in the following flowchart:

1. Find the preliminary stiffness E0 assuming ∆ = 0 and ∆t = 0.

2. Make the first guess ∆1 by solving restrictions with linearized constitutive relation ∆T1 = E0 ∆1 . This leads to
−1
∆1 = [Mt · E0 + Me ] ·m (32)

3. Call umat with ∆1 to get the constitutive stress f(∆1 ) and a better estimation of the tangential stiffness E1
4. Find the error N obtained substituting the exact (nonlinear) stress increment f(∆1 ) into the restrictions

N = Mt · f(∆1 ) + Me · ∆1 − m (33)

5. Find the correction c to the strain increment ∆1 such that N(∆1 + c ) = 0. For this purpose we expand
∂N
N(∆1 + c ) = N(∆1 ) + · c in the Taylor series and hence
∂∆
 −1
∂N ∂N
c = − · N with = Mt · E1 + Me (34)
∂∆ ∂∆

∂f
in which the new jacobian = E1 is used.
∂∆
6. Finally we update the strain increment

∆2 = ∆1 + c (35)

calculate f(∆2 ) and repeat the iteration.

11
9.4 Response envelopes in stress or in strain
A perturbation of stress *PerturbationsS or strain *PerturbationsE can be applied to an arbitrary state. It must be
described in the input file test.inp as a separate step in test.inp with the following syntax
∗PerturbationsE // h e r e ∗PerturbationsS for s t r e s s probes is also possible
n i n c , m a x i t e r , deltaTime
∗RoscoeIsomorph // h e r e ∗Rendulic is also p o s s i b l e ( o t h e r w i s e w ar n in g )
deltaLoad (1)

Perturbations of the first two components (of strain increments or stress increments) can be performed. They are applied
radially in ninc different directions equally distributed over the 2π angle in the space of the first two components. Usually
the transformed variables will be used here, namely *RoscoeIsomorph or *Rendulic. The *Cartesian or *Roscoe are
also possible although less common in perturbations. The size of the perturbation is described by R which has a special
meaning of the size of perturbation. For *RoscoeIsomorph it means
q
˘ P )2 + (∆
(∆ ˘ Q )2 = R (36)

9.5 Repetition of a group of steps

The keyword *Repetition introduces a group of nSteps which will be repeated nRepetitions times. Each step should
be defined according to its own syntax and no end of loop line is defined.
∗Repetition
nSteps nRepetitions
....
. . . . h e r e f o l l o w n S t e p s p r e c e d e d by t h e i r own keywords
...

It is the responsibility of the user to describe (without errors) the exact number of steps which should be repeated. For
a typical cyclic loading we will usually need a combination of a repetition of two *linearLoad steps or a repetition of a
single *CirculatingLoad steps.

9.6 Predefined popular paths

Several one-line steps have been predefined in the IncrementalDriverfor the convenience of geotechnical users. These
are: *OedometricE1, *OedometricS1, *TriaxialE1, *TriaxialS1, *TriaxialUEq, *TriaxialUq, *PureRelaxation,
*PureCreep, *UndrainedCreep
These paths define the principal stresses / strains assuming x1 -axial symmetry of the applied components. The material
response depends on umat and it need not be axisymmetric, of course. The shear components of strain are prescribed as
constant
∗OedometricE1
n i n c m a x i t e r dtime
ddstran (1) // l a t e r a l strain i s assumed c o n s t a n t

∗OedometricS1
n i n c m a x i t e r dtime
ddstress (1) // l a t e r a l strain i s assumed c o n s t a n t

∗TriaxialE1
ninc maxiter dtime
ddstran (1) // l a t e r a l stress i s assumed c o n s t a n t

∗TriaxialS1
n i n c m a x i t e r dtime
ddstress (1) // l a t e r a l stress i s assumed c o n s t a n t

∗TriaxialUEq
ninc m a x i t e r dtime
ddstran (2) // volume = c o n s t a n t , Roscoe ’ s D e l t a e p s i l o n q is applied

∗TriaxialUq
ninc maxiter dtime
ddstress (2) // volume = c o n s t , Roscoe ’ s D e l t a q i s applied

∗PureRelaxation
ninc maxiter dtime

∗PureCreep
ninc m a x i t e r dtime

12
∗UndrainedCreep // Roscoe ’ s D e l t a e p s v = 0 and D e l t a q = 0 other stress i n c a l s o =0
ninc m a x i t e r dtime

∗End // can be u s e d t o t e r m i n a t e t h e c a l c u l a t i o n

9.7 Enforced exit condition (new in 2016)

Each step-command may be optionally extended by a short inequality condition which will be evaluated at the end of each
increment. If this condition is satisfied the remaining increments of the current step will be skipped. Here we interrupt
an oedometric compression if the horizontal stress is large enough, say if T2 < −200, by writing
∗OedometricE1 ? s 2 < −200.0
100 10 1
−0.0002 // l a t e r a l s t r a i n i s assumed c o n s t a n t

9.8 Import a loading path from an external file (new in 2016)

You may have test results in form of a file with subsequent states listed in individual lines. For this purpose we write a
step command *ImportFile followed by the name of the file and we choose the columns to be input. We must ascribe
a column to each of six components of loading. However, if we ascribe the zero’th column then the zero value will be
prescribed to the corresponding component of stress or strain increment.
∗ImportFile followMe . inp | ncols ! name o f f i l e and number o f r e a l s t o be i n p u t p e r l i n e
ninc maxiter deltaTime ! numb . o f i n c r e m e n t s , max . numb . o f EI and s t e p time i n t e r v a l
∗Cartesian ! obligatory
i f s t r e s s (1) column ( 1 ) ! (0= s t r a i n 1= s t r e s s ) & column i n t h e f i l e . column==0 means no i n c r e m e n t
i f s t r e s s (2) column ( 2 )
...
i f s t r e s s (6) column ( 6 )
columnWithTime ! only i f deltaTime < 0 in the second l i n e

10 Non-isothermic paths (not implemented as yet)

In fully coupled thermal-stress analysis the following (essential) variables are used as an input for umat :

Tt = STRESS(NTENS) = pre-rotated Cauchy stress at the beginning of the increment

t = STRAN(NTENS)= logarithmic strain at the beginning of the incr. without thermal expansion.
∆ = DSTRAN(NTENS) Array of strain increments. If thermal expansion is prescribed in the same material definition13 , ∆
are the mechanical (i.e. total minus thermal) strain increments.
t = TIME(1/2) = Value of step/total time at the beginning of the current increment.
∆t = DTIME = Time increment.
θt = TEMP= Temperature at the start of the increment.
∆θ = DTEMP = Increment of temperature.

The following (essential) variables are defined/modified by umat as output:

Tt+∆t = STRESS(NTENS) = Cauchy stress at the end of the increment.

∂T/∂ = DDSDDE(NTENS,NTENS) = Jacobian of the constitutive model (for implicit time integration).
ṙ = RPL = rate of mechanical dissipation density, i.e. rate of heat production per unit time and volume at the end of the
incr. caused by mechanical work.
∂T/∂θ = DDSDDT(NTENS) = Variation of the stress increments with respect to the temperature.
∂ ṙ/∂ = DRPLDE(NTENS) = Variation of RPL with respect to the strain increments.
∂ ṙ/∂θ = DRPLDT = Variation of the rate of dissipation RPL due to the temperature change (6= 1/ specific heat)

The relation between corrections ct of stress, strain, heat and temperature are
o   n
cT ∂T/∂ ∂T/∂θ · c
n o
cṙ = cθ (37)
∂ ṙ/∂ ∂ ṙ/∂θ
13 Input lines of the section *MATERIAL of the Abaqus input file *.inp

13
For the non-isothermic loading, increments can be defined by a combination of 7 (and not 6) components chosen from
∆11 , ∆22 , ∆33 , ∆12 , ∆13 , ∆23 , ∆θ and ∆T11 , ∆T22 , ∆T33 , ∆T12 , ∆T13 , ∆T23 , ∆Q. If the increments of the first seven
quantities are known then no iteration is necessary and the incrementalDriver can follow the strain-temperature path
with just a single call to umat per increment. Otherwise a procedure similar to equilibrium iteration is necessary. In
applications to partially saturated soils one may want to interpret θ as the suction and Q as the degree of saturation.
In order to simulate undrained tests on partially saturated soils we have a constant water content so assuming constant
intrinsic bulk densities of water and skeleton we need to impose Sr e = const This leads in the language of our control
variables to the linearized form e ∆Q+Sr (1+e) (∆11 + ∆22 + ∆33 ) = 0. The coefficients in the above control equations
are not constant but depend on the state variables which vary within increments so strictly speaking not only a nonlinear
constitutive model but also a nonlinear control equation need to be solved.
For degree of saturation Sr and suction s one needs to define the direct dependence Sr (s) via the thermal properties of
the material, i.e. with the user’s subroutine

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)

Here the heat energy U = U per mass and the inverse specific heat ∂U /∂θ = DUDT may be defined. Moreover UMATH
defines the heat flux FLUX and its variation DFDT with temperature and as a function of the temperature gradient DFDG

A ? Linking incrementalDriver with umats written in C++

incrementalDriver is written in Fortran and umats are also recommended to be written in Fortran. However, incrementalDriver can also
be linked with umats written in C++ (although Abaqus people do not recommend C++). This section describes how to write a C++ umat
( umat.cpp ) and how to link it with incrementalDriver or with Abaqus. The presented method has been tested under Windows XP with
Intel 9.0 Fortran compiler and with Microsoft Visual C++ .NET Version both under Microsoft Visual Studio .NET 2003 (MSDE 7.1 and Ms
.NET Framework 1.1). It is also running with Abaqus 6.6.
If you like using the DOS window, in order to build incrementalDriver with a C++ umat you may try something like

> cl /I<include-directory> /c umat-full.cpp

> ifort incrementalDriver.f usolve.f umat-full.obj /link /out:MixedDriver.exe

however the MSDE (Microsoft Developer Environment) allows for nice simultaneous debugging of both Fortran and C++ in a single project.
Probably the easiest way to develop and to test umat.cpp under incrementalDriver is to start two projects one with fortran files only and
the other with C++ files only. Let us call them

1. LA-Project containing incrementalDriver.f, usolve.f and var_elastic_umat.f

2. Pure-Project containing pure.cpp and umat-full.cpp and in my case a header file tensor.h

Each project should be tested individually before we start to mix them. The var_elastic_umat.f is a version of a Fortran umat. Fortran
umats are described in detail in the Abaqus manual. The Fortran umat is called by the main program contained in the incrementalDriver.f
file. The file usolve.f also belongs to the fortran project because it contains a solver (necessary for incrementalDriver).
In the C++ project, the pure.cpp file contains the main calling unit. The C++ umat routine is contained in the file umat-full.cpp. The
main program in pure.cpp is necessary for formal reasons only (there must be a main in the project). Apart from initialization of variables and
calling umat it does practically nothing. C++ programmers not familiar with MSDE may face the problem of ”procompiled headers” (this
option is default in MSDE). The way around it is to right-click on the pure project in the Solution Explorer Window and under Properties
| C/C++ | Procompiled Headers to choose not using the latter (do this for the Release and for the Debug environment). Compile the C++
project within the ”Debug” environment.
For usage with pure.cpp and with incrementalDriver.f the umat code in umat-full.cpp should be defined like this

extern "C"
void UMAT(double *stress, double *statev, double *ddsdde,
double *sse, double *spd, double *scd, double *rpl, double *ddsddt,
double *drplde, double *drpldt, double *stran, double *dstran,
double *tajm, double *dtajm, double *temp, double *dtemp, double *predef,
double *dpred, char *cmname, int *ndi,
int *nshr, int *ntens, int *nstatv, double *props,
int *nprops, double *coords, double drot[][3], double *pnewdt,
double *celent, double dfgrd0[][3], double dfgrd1[][3], int *noel,
int *npt, int *layer, int *kspt, int *kstep,
int *kinc){
.........
}

14
Of course, this should be repeated as a prototype in pure.cpp. The main in pure.cpp should be something like

int _tmain(int argc, _TCHAR* argv[])

{ int i, kinc, kspt, kstep, layer, ndi, nshr, ntens, nstatv, nprops, noel, npt;
double celent, coords[3], *ddsdde, ddsddeFull[NTENS][NTENS], ddsddt[NTENS],
dfgrd0[3][3], dfgrd1[3][3], dpred[1], drot[3][3], drplde[NTENS],
drpldt, dstran[NTENS], stran[NTENS], temp, dtemp, pnewdt, predef[1], props[NPROPS],
rpl, scd, spd, sse, statev[NSTATV],
stress[NTENS], time[2], dtime;
char* cmname="wo2 ";
ddsdde = &ddsddeFull[0][0]; // 1-D ddsdde pointer shows to ddsddeFull[][] data
ndi=NDI; noel=NOEL; nprops= NPROPS; npt=NPT; nshr=NSHR ; nstatv=NSTATV ;ntens=NTENS ;
....
}

where the upper case variables denote the global constants. The above heading is followed by setting the values of the parameters and by
calling of umat

UMAT(stress, statev, ddsdde, &sse, &spd, &scd, &rpl, ddsddt,

drplde, &drpldt, stran, dstran, time, &dtime, &temp, &dtemp, predef,
dpred, cmname, &ndi, &nshr, &ntens, &nstatv, props,
&nprops, coords, drot, &pnewdt, &celent, dfgrd0, dfgrd1, &noel,
&npt, &layer, &kspt, &kstep, &kinc);

The code of incrementalDriver is identical for C++-umats and for Fortran-umats. The call-of-umat line has the common form

call UMAT(stress,statev,ddsdde,sse,spd,scd,
& rpl,ddsddt,drplde,drpldt,
& stran,dstran_Cart,time,dtime,temp,dtemp,predef,dpred,cmname,
& ndi,nshr,ntens,nstatv,props,nprops,coords,drot,pnewdt,
& celent,dfgrd0,dfgrd1,noel,npt,layer,kspt,kstep,kinc)

Suppose our both projects, the LA-Project and the Pure-Project, can be built and they both run correctly. We may now build the mixed-
language exe. For this purpose we remove var_elastic_umat.f from the Pure-Project and in the properties of this ”Debug” project (righ-tclick
in the Solution Explorer Window) under Properties | linker | Input we put under ”Additional Dependencies” the full path and name of the
object file from the pure project. In my case it is:
D:\i11\papers\element-tests\c\pure-C\pure\pure\Debug\umat-full.obj.
Moreover, in the same window under ”Ignore Specific Library” we put LIBC.LIB.

B ? C++ umat used with AbaqusTM

Abaqus takes either Fortran var_elastic_umat.f or an object file umat-full.obj from which it can internally produce a dll and link it. This
necessitates:

• a small modification of the heading in the umat-full.cpp.

• A compilation of the code in the ”Release” configuration or cl /I<include-directory> /c umat-full.cpp from DOS

The following (more or less) heading of the umat-full.cpp can be found on the Abaqus technical support pages

#define CHNAME(id) char* id, const unsigned int id ## _len

extern "C"
void _stdcall UMAT(double *stress, double *statev, double *ddsdde,
double *sse, double *spd, double *scd, double *rpl, double *ddsddt,
double *drplde, double *drpldt, double *stran, double *dstran,
double *tajm, double *dtajm, double *temp, double *dtemp, double *predef,
double *dpred, CHNAME(cmname), int *ndi,
int *nshr, int *ntens, int *nstatv, double *props,
int *nprops, double *coords, double drot[][3], double *pnewdt,
double *celent, double dfgrd0[][3], double dfgrd1[][3], int *noel,
int *npt, int *layer, int *kspt, int *kstep,
int *kinc){
.....
}

(the double ## is a so-called ”token-pasting” operator in the preprocessor language, but probably you know that already if you are writing in
C). Visit the Abaqus online support system
http://abaqus.custhelp.com/cgi-bin/abaqus.cfg/php/enduser/home.php?p_sid=ZByLlEHi
to learn how to write umat in C++ in operation systems different than MS Windows.

15
Having modified the umat-full.cpp we attempt to build the pure-Project under ”Release” configuration. The linking with pure will fail (unless
we modify suitably the calling line) but it does not bother us because only the semi product umat-full.obj is needed. We find this file in the
Release subdirectory of the root directory of the pure project. This is the file which we put in the working directory of Abaqus. Now we may
start our Abaqus job with the DOS command line
abaqus j=1 inp=inputfile.inp user=umat-full.obj
instead of the usual
abaqus j=1 inp=inputfile.inp user=var_elastic_umat.for

C ? C++ umat used with Tochnog

Tochnog is a commercial FE-Program which allows for using umat with the syntax almost identical with the one of Abaqus. The C code of
umat is described on the Tochnog www-pages or on http://www.koders.com/ if you search for umat.c. The code looks like this

typedef long int integer;

typedef double doublereal;
typedef short ftnlen;

int umat_(stress, statev, ddsdde, sse, spd, scd, rpl, ddsddt,

drplde, drpldt, stran, dstran, time, dtime, temp, dtemp, predef,
dpred, cmname, ndi, nshr, ntens, nstatv, props, nprops, coords, drot,
pnewdt, celent, dfgrd0, dfgrd1, noel, npt, layer, kspt, kstep, kinc,
cmname_len)
doublereal *stress, *statev, *ddsdde, *sse, *spd, *scd, *rpl, *ddsddt, *
drplde, *drpldt, *stran, *dstran, *time, *dtime, *temp, *dtemp, *
predef, *dpred;
char *cmname;
integer *ndi, *nshr, *ntens, *nstatv;
doublereal *props;
integer *nprops;
doublereal *coords, *drot, *pnewdt, *celent, *dfgrd0, *dfgrd1;
integer *noel, *npt, *layer, *kspt, *kstep, *kinc;
ftnlen cmname_len;
{
......
return 0;
}

Mind that the length of cmname is passed differently to Tochnog than to Abaqus and the name of the subroutine is int umat_ and not
extern "C" void _stdcall UMAT . Moreover cmname_len is of the type short and not of the type const unsigned int.

D ? incrementalDriver under Linux or Cygwin

The following description is provided by David Mašı́n http://www.natur.cuni.cz/~masin/eindex.php

To compile incrementalDriver using open-source gcc compiler

(http://gcc.gnu.org\verb for Linux OS, http://www.cygwin.com for Windows OS)
and link it with C++ umat proceed as follows:

1. Compile C++ umat using command

gcc -c *.cc
(tested with umat_prague)
2. Rename aba_param.inc to ABA_PARAM.INC (In Linux only, due to case-sensitive filenames)
3. Compile incrementalDriver files using commands
gfortran -c usolve.f
gfortran -c incrementalDriver.f
Note that usolve.f has been compiled first.
The module unsymmetric_module.mod needed for the compilation of incrementalDriver.f is created during the compilation of usolve.f
4. Link C++ umat with incrementalDriver and create incrementalDriver executable:
gfortran -o incrementalDriver *.o -lstdc++ umatdir/umat_prague/*.o
umatdir should be replaced by specific directory in which umat_prague is located.
Note that gcc option -lstdc++ is crucial for linking, as otherwise C++ libraries needed by umat_prague are not loaded by gfortran.

16
D.1 ? umatONE.obj for AbaqusTM from umatONE.f
1. put all fortran files (e.g. umat.f, sigini.f, sdvini.f . . . ) into a single file umatALL.f (modules first)
2. create a dummy fortran program. e.g.
program nic
use niemunis_tools_lt
real(8) :: T(3,3)
T = delta
write(*,*) ( T .xx. T )
end program nic
3. create a ”Release” project under Intel FortranTM 8.3 MS Developer Studio for Abaqus 6.6 or under Compaq Visual Fortran for
Abaqus 6.5 (patches to CVF are necessary for niemunis_tools_lt)
4. include nic.f and umatALL.f in the project
5. if under Intel FortranTM 8.3 then set :
Properties| Fortran| ExternalProcedures| CallingConvention| CVF
6. build the project
7. find umatALL.obj in the release subdirectory
8. use umatALL.obj like this: abaqus j=1 inp=blabla.inp user=umatONE.obj

E ? General remarks on mixed Fortran/C++ codes

call umat() needs capital letters in the name of the function in C.
The C function’s formal arguments must be declared as pointers to the appropriate data type.
In C, the first four elements of an array declared as X[3][3] are: X[0][0] X[0][1] X[0][2] X[1][0]
In Fortran, the first four elements are: X(1,1) X(2,1) X(3,1) X(1,2)

Language Array Declarations Array Reference from Fortran

Fortran: real(8), DIMENSION :: x(i,k) x(i,j )

C++ : double x[ k ][ i ]; x(i-1,j-1)

In Fortran, you can specify these conventions in a mixed-language interface with the INTERFACE statement or in a data or function declaration.
C/C++ and Fortran both pass arguments in order from left to right. You can specify these conventions with ATTRIBUTES options such as
C or STDCALL. Individual Fortran arguments can also be designated with ATTRIBUTES option VALUE or REFERENCE.

References
[1] Hibbitt, Karlsson & Sorensen Inc. Abaqus 5.8 User’s Manual Volume III, 1998. 1
[2] E. Hinton and D.R. Owen. An introduction to finite element computations. Pineridge Press Ltd., Swansea, U.K.,
1979. 6
[3] T.J.R. Hughes and J. Winget. Finite rotation effects in numerical integration of rate constitutive equations arising in
large-deformation analysis. International Journal for Numerical Methods in Engineering, 15(11):1862–1867, 1980. 5,
5
[4] P.I. Lewin and J.B. Burland. Stress-probe experiments on saturated normally consolidated clay. Géotechnique, 20:38–
56, 1970. 7
[5] M. M. Rashid. Incremental kinematics for finite element applications. International Journal for Numerical Methods
in Engineering, 36:3937–3956, 1993. 5
[6] P. Royis and T Doanh. Theoretical analysis of strain response envelopes using incrementally non-linear constitutive
equations. International Journal for Numerical and Analytical Methods in Geomechanics, 22:97 – 132, 1998. 7

17
Index
*Cartesian, 9, 18
*CirculatingLoad, 13
*DeformationGradient, 4
*LinearLoad, 3, 4, 13
*ObeyRestrictions, 16
*OedometricE1, 18
*OedometricS1, 18
*PerturbationsE, 6, 17
*PerturbationsS, 6, 17
*PureCreep, 18
*PureRelaxation, 18
*Rendulic, 6, 9, 18
*Repetition, 18
*Roscoe, 7, 9, 18
*RoscoeIsomorph, 6, 9, 18
*TriaxialE1, 18
*TriaxialS1, 18
*TriaxialUEq, 18
*TriaxialUq, 18
*UndrainedCreep, 18

18