User-supplied Subroutines
Arno Wolthers, Kesio Palacio and Gerd-Jan Schreppers, February 2011
Abstract:
This paper explains the functionality of user-supplied subroutines in DIANA.
The principles of how parts of user-defined source code can be used in combination with the standard
DIANA program are explained. An overview of different entries for user-supplied subroutines is given
together with an example. Required compilers for different hardware software combinations are explained
and working procedures are described at a glance.
Introduction
DIANA offers you, as an end-user, the opportunity
to supply FORTRAN source code of some
predefined subroutines. There are user-supplied
subroutines available for the following functions:
► Dependency of elastic parameters and viscoelastic parameters such as Young’s modulus
on ambient influences.
are related to nonlinear analysis, there are some
exemptions. E.g. the derived results subroutine is
also available for linear static analysis. A complete
overview of which analysis application should be
relinked with the user-supplied subroutine is given
in appendix A.3 of the Analysis Procedures
Volume of the DIANA User’s Manual.
http://tnodiana.com/upload/files/DIANA/943/HTML/
Diana.html
► Nonlinear elastic stress-strain relations
► Dependencies of material parameters for
plasticity and cracking models on ambient
influences or e.g. plastic hardening curves, or
shear-retention as function of crack-normal
strain or other crack status parameters.
► Definition of shrinkage strain as function of
ambient influences such as temperature, time
and maturity.
► General User-supplied Material definition, with
possibility to define several user-parameters
and internal status-parameters. In this
subroutine the behavior can be defined as
function of ambient influences such as
temperature, time and maturity.
► User-supplied definition of interface behavior.
The interface behavior can be defined using
several user-parameters and internal statusparameters. In this subroutine the behavior
can be defined as function of ambient
influences such as temperature, time and
maturity.
► Special
user-supplied
subroutines
for
liquefaction materials and Maekawa model,
which allow the user to make modifications in
these models.
Basic Assumptions and Definitions
In the user-supplied subroutines, the exchange
with data from the DIANA data-structure is done
via the argument-list of the subroutine. The
consistency in interpretation of these arguments is
guaranteed for future versions of DIANA. In special
cases the TNO DIANA Support can advise you in
using additional data-exchange procedures, such
as direct access-routines to and from the DIANA
data-structure and usage of common-blocks.
However, for these mechanisms no consistency in
function is given for future versions.
There are two ways to supply DIANA with usersupplied subroutines (USS): As FORTRAN source
code or as external library.
When the USS is provided as source-code DIANA
will compare the time-stamps of the USS-sourcecode file and the respective DIANA application
executable. If the source-file is more recent then
the executable DIANA will automatically call the
compiler, translate the source-code into object
code and link a new executable. DIANA will log
with a command like:
► User-defined derived results for beamelements and plate and shell elements.
instal nl41 /usr4/user/trainee/diana/
binseg/ap/nl41
A full overview of available subroutines can be
found in chapter 11 of the Material Library volume
of the DIANA User’s Manual.
The new private executable nl41 for nonlinear
analysis will be installed in the folder
/usr4/user/trainee/diana/binseg/ap.
The DIANA program consists of different
executables for different analysis applications.
Although most of the User-supplied subroutines
© TNO DIANA BV, The Netherlands
This executable will be used instead of the
standard nonlinear analysis executable until the
private executable is removed. The user is advised
User-Supplied Subroutines
to remove this private executable when he does
not use the user-defined subroutine any more. The
FORTRAN and C++ compilers are not included in
the DIANA program and must be arranged by the
user. For successful usage of user-supplied
subroutines that are provided as source-code, it is
important that the equivalent compilers and
compiler versions are used as have been used in
compiling the standard DIANA program. An
overview of platforms and compilers can be found
on the TNO DIANA web-site at:
http://tnodiana.com/DIANA-supported-platforms
Next to the FORTRAN compiler a UNIX style
toolkit cygwin32 utilities is required. The latter is
provided on the DIANA installation package, and
needs to be activated during installation. Please
note that the usage of user-supplied subroutines
require a specific license option to be activated.
More detailed explanation on how compilers
should be installed is given on the TNO DIANA
web-site at:
Page | 2
presents the subroutines and functions which are
particularly useful in combination with the usersupplied subroutine option. See the Appendix A.4
in the Analysis Procedures Volume of the DIANA
User's Manual for full description of the service
library subroutines. These routines cannot be used
in USS which are provided as an external library.
Example
DIANA offers the user-supplied subroutine
mechanism to specify a general nonlinear material
behavior. This model requires dedicated input data
in table 'MATERI' and the code for user-supplied
subroutine USRMAT.
The following information from table 'MATERI' is
passed to the user-supplied subroutine USRMAT.
(syntax)
http://tnodiana.com/DIANA-FAQ-USS
When the USS is provided as an external library,
the user has more flexibility in using compilers and
specific compiler versions. For the case of Visual
Studio 2008 the procedure is described at:
USRMAT
http://tnodiana.com/content/How-do-I-create-usersupplied-dll-using-Visual-Studio-2008
An alternative approach for building an external
library with the supported compiler using the
command line is given in appendix A.1.3 of the
Analysis Proceedings Volume of the DIANA User’s
manual.
The use of USS as external libraries has the
disadvantage that common-blocks from the DIANA
internals and standard DIANA functions cannot be
used in the USS. In this case the user defines in
the DIANA command-file that an external library
must be used and where the external library can
be found. No new DIANA executable will be linked.
specifies that a general material model is
determined via user-supplied subroutine
USRMAT. The keyword usrmod may be
used as a switch in the subroutine. This
gives you the opportunity to code various
material models in one single subroutine.
USRVAL
usrval is a series of material parameters.
These parameters cannot be modified in
the subroutine.
USRSTA
usrsta are the initial values of a series of
internal state variables. These variables
may be used and modified in the
subroutine.
USRIND
Programmers’ Service Libraries
The DIANA programming environment comes with
a set of service libraries of utility routines. The
libraries are especially helpful when coding usersupplied subroutines because the routines are
extensively tested and often optimized. When
applying user-supplied subroutines, you are
encouraged to call the routines of the DIANA
service libraries whenever appropriate. DIANA
programmers’ service libraries are subdivided for
some basic tasks such as matrix and vector
manipulations, I/O operations etc. This section
© TNO DIANA BV, The Netherlands
usrind are the initial values of a series of
integer indicator variables. These variables
may be used and modified in the
subroutine.
(file.dat)
'MATERI'
1
YOUNG
POISON
USRMAT
USRVAL
USRSTA
USRIND
'END'
30000.0
0.15
HSCMOD
6.0 0.12 30.0
0.0 0.0
0 0
90.0 5.0 30.0
User-Supplied Subroutines
In addition to the data for the user-supplied
subroutine, this example also inputs values for
Young's modulus E and Poisson's ratio ν. These
values are necessary for the preliminary linear
analysis. If you need these values in the usersupplied subroutine, then you can take them from
the DIANA data-structure via a special access
routine GTC [see Vol. Analysis Procedures].
If USRMAT is specified in table 'MATERI' then
subroutine USRMAT must be supplied. This
routine must update the stress vector, the user
state variables and indicators, and the tangent
stiffness matrix.
(FORTRAN)
$
$
$
SUBROUTINE USRMAT( eps0, deps, ns, age0, dtime, temp0,
dtemp, elemen, intpt, coord, se, iter,
usrmod, usrval, nuv, usrsta, nus,
usrind, nui, sig, stiff )
Page | 3
subsequent steps they come in from the
final iteration of the previous step. They
must always go out for the current
iteration.
sig
is the total stress vector, it comes in from
the final iteration of the previous step and
must go out for the current iteration.
stiff
is the tangent stiffness matrix, it comes in
from the previous step and must go out for
the current iteration.
Example
A simple example of the user-supplied material
model USRMAT in a transient analysis is the
modeling of a viscoelastic material. In this example
the modeling of the creep function J(t, t0) with a
Kelvin chain will be discussed. The model will be
derived for the application with truss elements in
which the strain vector is given by ε = {ε} and the
stress vector by σ = {σ}. Consider a simple
viscoelastic model, represented by the rheological
model of the figure below.
Rheological model of a Kelvin chain
usrmod
is the user-supplied model name from
input table 'MATERI'. This name can be
used as a switch to various material
models coded in one single subroutine.
usrval
are the user-supplied material parameters
from input table 'MATERI'. These
variables shall not be updated in this
subroutine!
usrsta
are the user-supplied state variables.
usrind
are the user-supplied integer indicator
variables.
At the start of the first step the values of
usrsta and usrind come in as the ones
specified in input table 'MATERI'. In
© TNO DIANA BV, The Netherlands
This Kelvin chain has one unit with a linear spring
only and one unit with a dashpot and a linear
spring. With this model the creep will be bounded if
the time goes to infinity. The first unit has elastic
spring stiffness E0, the second unit elastic spring
stiffness E1 and a dashpot viscosity η1. The
governing equation is now given by the equilibrium
condition
̇
With the compatibility conditions
{
̇
̇
̇
This can be written as the following rate equation
̇
̇
User-Supplied Subroutines
Page | 4
A stable integration algorithm for a rate equation is
the Central Difference algorithm, which is defined
as
Δ
Δ
Δ
Δ
Applying this scheme to the integration of the
stress and strain and substituting the relations into
the differential equation above, results in the
equation for the incremental stress
(
)Δ
Δ
Δ
The updated stress is finally given by
Δ
Δ
and the tangent stiffness relation by
Δ
Δ
(
Δ
)
The implementation of user-supplied subroutine
USRMAT is given below.
(usrmat.f)
C
C...
C...
C
SUBROUTINE USRMAT( EPS0, DEPS, NS, AGE0, DTIME, TEMP0,
DTEMP, ELEMEN, INTPT, COORD, SE, ITER,
USRMOD, USRVAL, NUV, USRSTA, NUS,
USRIND, NUI, SIG, STIFF )
USER-SUPPLIED MATERIAL MODEL
RETURN UPDATED STRESS AND TANGENTIAL STIFFNESS MATRIX
CHARACTER*6
INTEGER
USRMOD
NS, NUV, NUS, NUI, ELEMEN, INTPT, ITER,
$
USRIND(NUI)
DOUBLE PRECISION EPS0(NS), DEPS(NS), AGE0, DTIME, TEMP0,
$
DTEMP, COORD(3), SE(NS,NS), USRVAL(NUV),
$
USRSTA(NUS), SIG(NS), STIFF(NS,NS)
C
DOUBLE PRECISION DSIG, E0, E1, ETA1, FAC1, FAC2, FAC3
C
C...
GET
E1
=
ETA1 =
E0
=
END
The user-supplied material parameters which are
given in the input data item USRVAL are the linear
stiffness E1 of the Kelvin unit, the dashpot viscosity
η1 of the Kelvin unit and the linear stiffness E0 of
the spring respectively. There are no user-defined
status variables, so USRSTA and USRIND will not
be defined in the data file. The following could be
the data file for this example.
)Δ
(
$
$
$
C
(file.dat)
Δ
Δ
SIG(1)
= SIG(1) + DSIG
STIFF(1,1) = ( 0.5D0 * FAC2 * DTIME + FAC3 * ETA1 ) /
$
FAC1
Δ
̇
{
C
MATERIAL DATA FROM USRVAL
USRVAL(1)
USRVAL(2)
USRVAL(3)
'COORDINATES' DI=2
1
0.
0.
2
100.
0.
3
100.
0.
'ELEMENTS'
CONNECTIVITY
1 L2TRU 1 2
2 L2TRU 1 3
MATERIALS
1
1
2
2
GEOMETRY
1
1
2
1
'MATERIALS'
1
YOUNG
100.0
USRMAT KELVIN
USRVAL 100.0 2500.0 100.0
2
YOUNG
100.0
KELVIN 2
,1 YOUNG
100.0
,2 YOUNG
100.0
RETTIM 25.0
'GEOMETRY'
1 CROSSE
1.0
'DIRECTIONS'
1
1.
0. 0.
2
0.
1. 0.
3
0.
0. 1.
'SUPPORTS'
/ 1 / TR 1
'LOADS'
CASE 1
NODAL
2
FORCE 1
1.0
3
FORCE 1
1.0
'END'
Post processing
parameters
of
user
defined
status
For the general user-supplied material model, the
stress and strain vector can be processed in the
usual way: component-wise or in the principal
directions. The same holds for the traction vectors
of the user-supplied interface model. The vector of
internal state variables for user-supplied models
USRSTA can only be processed component-wise
via the keyword STATUS USER.
C
FAC1 = 0.5D0 * DTIME + ETA1 / ( E1 + E0 )
FAC2 = ( E0 * E1 ) / ( E0 + E1 )
FAC3 = E0 / ( E0 + E1 )
C
$
DSIG = DTIME * ( FAC2 * EPS0(1) - SIG(1) ) +
( 0.5D0 * FAC2 * DTIME + FAC3 * ETA1 ) * DEPS(1)
DSIG = DSIG / FAC1
© TNO DIANA BV, The Netherlands
Because FX+ for DIANA cannot handle real value
results in integration points, user-supplied material
result items cannot be used in combination with
this output device.