Preparing input for incrementalDriver

A.Niemunis

November 22, 2012

1 Introduction
The purpose of IncrementalDriver is testing of routines describing constitutive models ∆T = f(∆, . . . ). The con-
stitutive routines are external (not a part of IncrementalDriver) and they should be written according to Abaqus R

standard conventions for umat. Being given all state variables and a strain increment ∆, umat calculates a strain-
controlled increment ∆T = f(∆, . . . ) and updates the state T+= ∆T; . . . . Moreover umat should return the Jacobian
matrix (∂T/∂) necessary for equilibrium iteration. IncrementalDriver can apply series of such increments following
a prescribed strain path. In each increment it invokes umat for this purpose. IncrementalDriver can also follow stress
paths or mixed paths calling umat possibly many times within a single increment in an iterative process. This procedure
is similar to equilibrium iteration. The prescribed components of strain increment or strain increment are termed the
load and the calculated increments are called the response of the material.
IncrementalDriver is a Fortran90 project which consists of the following files

incrementalDriver.f
usolve.f compile
aba_param.inc −→ incrementalDriver.exe
umat.f
niemunis_tools_lt.f

After compilation the resulting program needs three input files and 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 default names of the input files can be overridden by the command-line parameters. This example keeps the
defaults
incrementalDriver test=test.inp param=parameters.inp ini=initialconditions.inp out=x.out verbose=true

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.

1.1 General syntax

For all input files the following rules apply

• No empty lines;
• No comment lines;
• The end-of-line comments should start with #. Insert some spaces (say 15) between input strings and #. In lines with
purely numerical input # is not necessary to mark an end-of-line comment.
• Input values of integer-type must not have a decimal point;

1
• 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, default filename: parameters.inp

The current material name cmname and the number nprops of material constants
cmname
nprops should be followed by a list of constants props(1), props(2) .... The meaning of props
props(1) depends on their internal interpretation in umat.f. Input just one material constant
props(2) per line. The end-of-line comments after the data are allowed but note that cmname is
... character(len=80).
props(nprops)

3 Initial conditions, default filename: initialconditions.inp

The initial conditions are read from the file initialconditions.inp.
ntens
stress(1)
Remarks:
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 EOF is encountered while reading statev( ) then the remaining components
... of statev( ) will be padded with zeros.
statev(nstatv)

4 Description of tests path: default filename test.inp

The first line of test.inp

outputFileName # optional heading copied to the outputFile

is name character(len=260) of the output file. 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 the first line (=heading). 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 of incrementalDriver. This
may be useful for writing scripts. The heading (i.e. the text after #) cannot be overridden.

4.1 Proportional stress/strain paths

The whole path consists of steps and each step consists of increments. During proportional loading all increments within
the step are identical. In order to prescribe such linear loading 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 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 , ∗ R e n d u l i c
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)

2
 • *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 − 21 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.

In the current version of the program there is no convergence criterion. The fixed number maxiter of
equilibrium iterations is carried out irrespectively of 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 indeed
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.f 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 ! number o f i n c r e m e n t s , max . number o f EI ( 1 s u f f i c e s h e r e ) and t h e s t e p t i m e i n t e r v a l
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)

n o
This example defines nine components of the deformation gradient F̆11 , F̆22 , F̆33 , F̆12 , F̆21 , F̆13 , F̆31 , F̆23 , F̆32 between
1
the the beginning of the step and the end of the step. The ninc equal increments are calculated with ∆F = n (F − 1)

4.2 Harmonic load *CirculatingLoad

A single oscillation loop can be input with *CirculatingLoad
∗CirculatingLoad
ninc maxiter deltaTime ! number o f i n c r . p e r c y c l e , number o f EI and time step
∗Cartesian ! a l t e r n a t i v e s here : ∗Roscoe , ∗RoscoeIsomorph , ∗ R e n d u l i c
i f s t r e s s ( 1 ) deltaLoadCirc ( 1 ) phase0 ( 1 ) deltaLoad ( 1 ) ! 1/0 Flag , 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 e a r 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 )

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

3
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.3 Definition of loading path by applying restrictions

The mix-control tests can be defined via *ObeyRestrictions. This requires 6 linear equations containing stress and/or
strain increments per step, e.g.
∗ObeyRestrictions
100 20 1.0 ! ninc , maxiter , deltaTime
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. The restrictions have the formal structure
Mt · ∆T + Me · ∆ = m (2)
t e
whereinPall components
P of M , M 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 some formal rules:
• The input line cannot be longer than 120 characters.
• No brackets (), no exponents ** or divisions / may appear.
• 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.
• 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 .
• Only numerical coefficients are allowed, i.e. only 4.0 *sd1 = 1.0 instead of two lines t = 4 and t*sd1 = 1.0.
• In all multiplications the asterisk * is obligatory (i.e. not 3.0 sd3 = 2.0 but 3.0*sd3 = 2.0 ).
• The summands are separated by + or -.
• The spaces are ignored (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 on the right-hand side is allowed.
The end-of-line comments must begin with !. Exactly 6 lines with restrictions must be input.

4.4 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
ninc , maxiter , 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
4.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. 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
...

4.6 Predefined popular paths

Several one-line steps have been predefined in incrementalDriver for 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

5
∗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

∗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