Preparing input for incrementalDriver

A.Niemunis

October 17, 2016

1 Introduction
The purpose of the IncrementalDriver is the simulation of various element tests by calling a constitutive routine umat
in a series of time increments. In this way the constitutive routine can be tested under debugger before being used in the
commercial FE program Abaqus R . The subroutine umat obtains the current state of a material and a strain increment
∆. It uses this information to update the state, i.e. to find stress Tt+∆t = f(∆, Tt . . . ) and other state variables after the
increment. The umat is an independent piece of software usually written in Fortran 90. It should be available as a source
code1 to be compiled and linked with IncrementalDriver . The routine umat should be written strictly according to
Abaqus R standard described in Abaqus R User Subroutines Reference Manual 1.1.40. A new constitutive model can be
written as umat and be tested with the help of IncrementalDriver . Although a very simple linear elastic constitutive
model is delivered with the IncrementalDriver as a separate file umat , this file should be replaced by the constitutive
model of interest, of course.
Given all state variables statev and a strain increment dstran = ∆, umat calculates internally a stress increment ∆T =
f(∆, . . . ) and adds it to the stress Tt+∆t = Tt + ∆T. Also the state variables from statev should be updated according
to their evolution equations. Moreover, umat should return the stiffness, i.e. the Jacobian matrix (∂T/∂). This stiffness
is used in IncrementalDriver if a stress path or a mixed path is prescribed, Section 4. IncrementalDriver can
apply series of increments obtained from a time-discretization of a prescribed strain path (t). In each increment Incre-
mentalDriver invokes umat . However, IncrementalDriver can also follow stress paths T(t) or mixed paths calling
umat possibly many times within a single increment in an iterative process. This procedure is similar to the equilibrium
iteration in the FEM: strain increments are adjusted to satisfy a condition formulated in stress. The prescribed compo-
nents of strain increment or strain increment are termed the load and the calculated (remaining) increments are called
the response of the material.

1.1 A typical simulation of an element test

IncrementalDriver is a Fortran 90 project which consists of the following files to be compiled and linked
incrementalDriver.f
compile
aba_param.inc −→ incrementalDriver.exe
umat.f & sub-files if any

After the compilation the resulting program incrementalDriver.exe can be executed, usually in DOS window. The
program needs three input files and it produces a single output file. The name of the output file should be specified in
the input file test.inp
initialConditions.inp
incrementalDriver.exe
parameters.inp −→ outputfile.out
test.inp

The above names of the files are default. They can be overridden by the command-line parameters. The example below
keeps the default names of input but redirects the output to x.out
incrementalDriver test=test.inp param=parameters.inp ini=initialconditions.inp out=x.out verbose=true

1 Otherwise read Appendix

1
 restricts the screen output during calculation. All command-line parameters of incrementalDriver are optional.
verbose=false
They may appear in any order. Spaces are treated as separators between the arguments. Spaces must not appear at =.

1.2 General remarks on preparing the input files

For all input files: test.inp, parameters.inp and initialconditions.inp the following rules apply:
• No empty lines and no comment lines;
• The end-of-line comments should start with #. Insert some spaces (say 10) between input strings and #.
• Input integers must not have a decimal point;
• Strings in input must not have apostrophes. They should 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)

2 Material constants (parameters.inp)

The initial conditions are usually read from the file parameters.inp. This name can
cmname
nprops be overridden in the command line as described in Section 1.1. In parameters.inp you
props(1) specify the material name cmname (only one material can be used) and the number
props(2) nprops of material constants. These two lines should be followed by a list of constants
... props(1), props(2) .... The meaning of props depends on their internal interpretation
props(nprops)
in umat . Input just one material constant per line. The end-of-line comments after
the data are allowed but note that cmname is character(len=80).

3 Initial conditions (initialconditions.inp)

The initial conditions are usually read from the file initialconditions.inp. This name
ntens
stress(1)
can be overridden in the command line, see Sec. 1.1.
stress(2) a. specify first ntens components of stress, usually ntens=6 and stress(1...6) are :
stress(3) T11 , T22 , T33 , T12 , T13 , T23
...
stress(ntens) b. The initial stress is always defined with the Cartesian components. As yet, you
nstatv cannot input initial Roscoe invariants instead.
statev(1)
statev(2)
c. If the end of file (EOF) is encountered while reading statev( ) then the remaining
... components of statev( ) will be padded with zeros.
statev(nstatv)

4 Prescribed path (test.inp)

The first line of test.inp contains the name character(len=260) of the output file.

outputFileName # optional heading which will be copied to the outputFile

If the character # is encoutered then the portion before # is interpreted as the name of the output file and the portion after
# is copied into the output file as heading2 . The output file name is obligatory and there is no default. The output file
name read from test.inp can be overridden by anyName.out in the command line if the argument out=anyName.out appears
in the command line invoking incrementalDriver. This may be useful for writing scripts. The heading (i.e. the text after
#) cannot be overridden.
The subsequent commands in test.inp describe sequences if increments that follow the desired path, i.e. each command
followed by parameters describes a steps (understood as in Abaqus R ) usually consisting of many increments.
2 For Easyplot I use output.ep # /td "nnnnnnnnyxnnnnn" in order to indicate which column should be plotted

2
4.1 A general description of step
Each step begins with a keyword like *LinearLoad, *Deformationgradient, *ImportFile etc. The second line is com-
mon for all steps. It contains the number of increments ninc, the desired number of equilibrium iterations maxiter and
the total time increment of the step (the time increment is deltaTime / ninc ). If you calculate thousands of increments
you can optionally suppress the output using the integer parameter every, after the colon. For example

∗LinearLoad
10000 10 5 0 0 . 0 : 100
...

applies 10000 increments with 10 iterations with the time increment of 0.05 and every 100th state will be written to the
output file. If the colon is absent then every = 1 is assumed, i.e. time, stress, strain and all state variables will be
printed after each increment.
The third line describes the type of components and can be *Cartesian, *Roscoe, RoscoeIsomorph etc. The next six
lines prescribe the components of stress or strain incremens. In very popular steps like TriaxialE1 or OedometricS1 the
type of components is not used and the description of loading is abbreviated.

4.2 Proportional stress/strain paths

During a proportional loading all ninc increments within the step are identical. In test.inp such linear loading is prescribed
by command *LinearLoad followed by some data and some options
∗LinearLoad
ninc maxiter deltaTime : every ! number o f i n c r e m e n t s , max . number o f e q u i l . i t e r a t i o n s and s t e p time i n t e r v a l
∗Cartesian ! other p o s s i b i l i t i e s here are : ∗Roscoe, ∗RoscoeIsomorph, ∗Rendulic
i f s t r e s s (1) deltaLoad (1) ! 0/1 F l a g (0= s t r a i n 1= s t r e s s ) and t h e change o f t h e 1 s t component i n t h e s t e p
i f s t r e s s (2) deltaLoad (2)
...
i f s t r e s s (6) deltaLoad (6)

The prescribed components deltaLoad of ”generalized load” and time interval deltaTime pertain to the whole step and
need to be apportioned to individual increments, usually dividing deltaLoad by ninc. Depending on the flag ifstress(i)
the respective (i-th) component of prescribed strain or stress increment is prescribed as ddstress(i) = deltaLoad/ninc
or strain increment dstran(i) = deltaLoad/ninc.
The required number of iterations maxiter is defined a priori and kept constant for all increments in a given step.
The time interval for a given step may be of importance for example in rate dependent constitutive models. The load
components may be defined using different components of stress and strain (work - conjugated)
• *Cartesian T11 , T22 , T33 , T12 , T13 , T23 and 11 , 22 , 33 , 12 , 13 , 23
• *Roscoe p, q, z, T12 , T13 , T23 and v , q , z , 12 , 13 , 23
• *RoscoeIsomorph P, Q, Z, T12 , T13 , T23 and P , Q , Z , 12 , 13 , 23
√ √
• *Rendulic T11 , 2T22 , Z, T12 , T13 , T23 and 11 , 222 , Z , 12 , 13 , 23
with:
p = −(T11 + T22 + T33 )/3, q = −(T11 − 12 T22 − 21 T33 ), z = −(T22 − T33 )
v = −(11 + 22 + 33 ), q = − 32 (11 − 21 22 − 12 33 ), z = −(22 − 33 )/2,
√ q √
P = −(T11 + T22 + T33 )/ 3 , Q = − 23 (T11 − 21 T22 − 12 T33 ), Z = −(T22 − T33 )/ 2,
√ q √
P = −(11 + 22 + 33 )/ 3, Q = − 23 (11 − 21 22 − 12 33 ), Z = −(22 − 33 )// 2
The change within
Pn theHstep of the Hencky strain  = ln U is applied in ninc equal increments ∆. In a 1D we would have
 = ln H
H0
n
= i=1 ln i
Hi−1 so equal strain increments ln HHi−1
i
= const do not imply equal increments of displacement.

3
 In the current version of the program there is no convergence criterion. The fixed number maxiter of
equilibrium iterations is carried out irrespectively of the convergence. After the last equilibrium iteration the
next load increment is applied, no matter whether the previous iteration was successful (small out of balance
stress) or not. Controlling stress components we should carefully compare the desired stress path with the one
actually applied to the material.

The loading prescribed in test.inp may demand a stress increment which cannot be achieved by the material (e.g.
going outside the yield surface despite softening). In this case the equilibrium iteration in IncrementalDriver
cannot achieve the required state. The calculation will not be interrupted, however. 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 and for large increments.
Equal increments of displacement can be also imposed by *DeformationGradient, for example:
∗DeformationGradient
n i n c m a x i t e r d e l t a T i m e : e v e r y ! number o f i n c , max . number o f E I , s t e p t i m e i n t e r v a l and s u p p r e s s e d o u t p u t
deltaLoad (1) ! i f s t r e s s f l a g i s a u t o m a t i c a l l y 0 (= s t r a i n −l i k e ) and t h e a x e s a r e ∗Cartesian
deltaLoad (2)
...
deltaLoad (9)

This example defines nine components of the deformation gradient {F11 , F22 , F33 F12 , F21 , F13 , F31 , F23 , F32 } between the
the beginning of the step and the end of the step. The ninc equal increments are calculated with ∆F = n1 (F − 1) They
all take the configuration at the beginning of the step as the reference.

4.3 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. The columns correspond to
different components of stress or strain, to different state variables or to time. Several non-numeric lines starting from a
character different than one of 1234567890+-. will be ignored, but only at the beginning of the imported file. In order
to simulate the test you need not formulate the loading programm from the end-values of such file dividing them to equal
increments. The time-intervals and the stress and strain increments obtained as differences between lines may be quite
irregular and are not always proportional. IncrementalDriver can extract a list of columns of your choice as a loading
programme. For this purpose we give the name of the file and we choose the columns to be followed. 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 : every ! number o f i n c r . , max . number o f EI and s t e p t i m e and s u p p r e s s e d o u t p u t
∗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 ) ∗ ImportFactor ( 1 ) ! multipler f o r input increments
...
i f s t r e s s (6) column ( 6 )
columnWithTime ! only i f deltaTime < 0 in the second l i n e

Optionally a column can be multiplied by a numerical ImportFactor. For example, if the imported file contains strains
in [%] in the first column you should read them into the IncrementalDriver with the line:
0 1 * 0.01
Similarly, if the imported file contains geotechnical stress in the second column you should read it with the line:
1 2 * -1 but not 1 2 * (-1)
The column with time can be also scaled by an ImportFactor. You must always give the name of an external file and
the number of columns to be read (there are no defaults). If the number if increments ninc is smaller than the number
of lines in the followMe.inp file then only a part of the path from the file will be executed. If ninc is larger than the
length of followMe.inp then the end-of-file will be encountered. In this case IncrementalDriver ends the step and
continue with the next step.
Hence you need not count the lines but be sure that each line begins with ncols numbers which can be input as
read(1 ,*) real(8), real(8) ... in fortran If deltaTime is positive in the second line of *ImportFile then it will be
set equal in all increment. If deltaTime is negative you must specify the column in the external file corresponding to the
7-th component of loading: the time.

4.4 Harmonic load

A single oscillation loop can be input with *CirculatingLoad

4
∗CirculatingLoad
ninc maxiter deltaTime : every ! number o f i n c r . , max . number o f EI and s t e p t i m e and s u p p r e s s e d o u t p u t
∗Cartesian ! a l t e r n a t i v e s here : ∗Roscoe, ∗RoscoeIsomorph, ∗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 A 1 , p h a s e w0 1 and s u p e r p o s e d l i n l o a d B 1
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 )

The applied load increments are calculated from

(0)
∆Li = ω̇∆tAi cos(ω̇t + ωi ) + Bi (1)

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
deltaTime = the period T so that ω̇ = 2*Pi/deltaTime
∆t = dtime = deltaTime/ninc
Ai = deltaLoadCirc(i) = amplitude
Bi =deltaLoad(i)/ninc = linear shift
t = time(1) + dtime/2 ! step time in the middle of the increment
(0)
ωi = phase0(i)

Closed harmonic loop can be superposed by a linear load Bi = deltaLoad(i)/ninc, with i = 1, . . . 6.

(0)
Each component of *CirculatingLoad may be individually shifted in phase using ωi = phase0(i) so that oval paths can
also be defined.

4.5 Definition of loading path by applying restrictions

The most flexible method for mixed control is offered by the command *ObeyRestrictions. This command reads 6
linear equations describing stress and/or strain change (per step not per increment), e.g.
∗ObeyRestrictions
100 20 1.0 ! n i n c , m a x i t e r , deltaTime, f u l l output ( equiv . to 100 20 1 . 0 : 1)
sd1 + 1 . 0 ∗sd2 + sd 3 = 0 ! r e s t r i c t i o n 1 = isobaric condition
ed1 = −0.01 ! restriction 2
ed3 = 0 . 0 ! ....
ed4=0
ed5 = 0 . 0 d0
ed6 = −0 ! restriction 6

The change of i-th stress component within the step is denoted as sdi. The change of j-th strain component within the
step is denoted as edj. All restrictions have the formal structure

Mt · ∆T + Me · ∆ = m , (2)
t
whereinPall components
P of M , Me and m are known. The k-th restriction with k = 1, . . . 6 should be input as a separate
t e
line : Mki sdi + Mkj edj = mk with sum over complementary indices i, j from 1 to 6. The parsing abilities of
i j6=i
IncrementalDriver are very limited. Here are the formal rules:
a. The input line cannot be longer than 120 characters.
b. No brackets (), no exponents ** or divisions / may appear.
c. An index number at components sd1,sd2,sd3,sd4,sd5,sd6,ed1,ed2,ed3,ed4,ed5,ed6 may appear at most once in
a restriction (at a strain or at a stress increment), i.e. one cannot write sd1 + sd1 = 0.0d0. Lower case is obligatory
for sd and ed.
d. 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 must be delegated to the RHS, i.e. sd1 + 1.0 + sd2 = 5.0
should be rewritten as sd1 + sd2 = 4.0 .
e. Only numerical coefficients are allowed. You should write 4.0 *sd1 = 1.0 instead of two lines t = 4 and t*sd1 = 1.0.
f. In all multiplications the asterisk * is obligatory. For example you should write 3.0*sd3 = 2.0 and not 3.0 sd3 = 2.0..
g. The summands are separated by + or -.

5
h. All spaces are ignored (spaces inside numbers cause errors, of course).
i. There must be just a single constant value in each restriction and it must appear on the right-hand side of the restriction.
The constant can be preceded by - but not by +. No multiplications like 3.0*4.0 are allowed for.
The end-of-line comments must begin with !. Exactly 6 lines with restrictions must be input.

4.6 Response envelopes in stress or in strain

A perturbation of stress *PerturbationsS or strain *PerturbationsE can be applied to an arbitrary state as a separate
step in test.inp with the following syntax
∗PerturbationsE ! here a l t e r n a t i v e l y ∗PerturbationsS for s t r e s s probes
n i n c , m a x i t e r , deltaTime
∗RoscoeIsomorph ! here a l t e r n a t i v e l y ∗Rendulic
deltaLoad (1)
q
Perturbations of the first two components of strain (or stress) are performed in such way that (∆ ˘ P )2 + (∆
˘ Q )2 =
deltaLoad(1) holds. The strain probes are applied radially in ninc different directions equally distributed. Use either
*RoscoeIsomorph or *Rendulic (only these transformations isomorph).

4.7 Repetition of a group of steps

The keyword *Repetition has just two parameters nSteps and nRepetitions. It must be followed by description of
nSteps steps which will be subsequently applied within a loop and repeated nRepetitions times.
Each step should be defined according to its own syntax. Exactly nSteps steps must be defined. Often nSteps is set
to 2 in order to describe a simple stress (or strain) cycle. There is no end-of-repetition-loop statement so the next steps
(beyond the position nRepetitions ) will be executed just once unless wrapped in another *Repetition.
∗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
...

For 1000 undrained triaxial stress cycles with the Amplitude q ampl = 10 kPa and with 1Hz we can write:

a saw-like version with *LinearLoad or a harmonic version or a saw-like with predefined shearing
*LinearLoad ∗Repetition ∗TriaxialUq
10 10 0.25 1 1000 10 10 1 . 0
*Roscoe ∗CirculatingLoad 10.0
0 0 40 10 1.0 ∗Repetition
1 10 ∗Roscoe 2 1000
0 0 0 0 0 0 ∗TriaxialUq
0 0 1 10 0 0 20 10 0.5
0 0 0 0 0 0 −20.0
0 0 0 0 0 0 ∗TriaxialUq
*Repetition 0 0 0 0 20 10 0.5
2 1000 0 0 0 0 20.0
*LinearLoad ∗TriaxialUq
20 10 0.5 10 10 0.2
*Roscoe −10
0 0
1 -20
0 0
0 0
0 0
0 0
*LinearLoad
20 10 0.5
*Roscoe
0 0
1 20
0 0
0 0
0 0
0 0
*LinearLoad
10 10 0.25
*Roscoe
0 0
1 -10
...

6
4.8 Predefined popular paths

Several short step descriptions have been predefined in incrementalDriver for convenience of geotechnical users. They
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 : every
ddstran (1) // l a t e r a l s t r a i n i s assumed c o n s t a n t

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

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

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

∗TriaxialUEq
ninc m a x i t e r dtime : e v e r y
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 : e v e r y
ddstress (2) // volume = c o n s t , Roscoe ’ s D e l t a q i s applied

∗PureRelaxation
ninc maxiter dtime : e v e r y

∗PureCreep
ninc m a x i t e r dtime : e v e r y

∗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 : e v e r y

∗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

5 Enforced exit from a step on a predefined condition (new in 2016)

Each step-command may be 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. The next step will be commenced
from the currently reached state. For example, we may 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 : 2
−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

The exit condition is optional, so the old input files should work fine with the new version. The exit condition must be
written in the same line as the description of step after the separator ? and the whole line must not exceed 40 columns.
You can use addition and multiplication, but both on the left-hand side of the inequality only. The right-hand side must
be a single number. Parsing rules from Section 4.5 apply. No end-of-line comments and no = character may appear (sharp
inequalities only).
Only the following variables can be used in the exit condition:
s1,s2,s3 for principal stress components (tension negative) T1 , T2 , T3
e1,e2,e3,e3 for principal strain components (tension negative)1 , 2 , 3
p,q,P,Q for geotechnical stress invariants
ev,eq,eP,eQ for geotechnical strain invariants.
v1,v2,...v9 for state variables (just the first nine have been implemented)
q,Q,eq,eQ deviatoric invariants are signed, e.g. q = −(T1 − T3 ) assuming triax. symmetry T2 = T3

7
6 End
In order to terminate calculations the command *End can be used. Commands behind *End will not be executed.