User subroutines enable you to modify the behavior of a material model or to create your own material model. You can also combine material subroutines and use them together. User-defined state variables are supported for many material subroutines and for subroutine combinations.
The following topics are available:
For information about each material subroutine, see Subroutines for Customizing Material Behavior in the Programmer's Reference.
Generally, a given element supports a user subroutine if the native material is supported by that element.
For example, UserHyperAniso is supported by elements that support anisotropic hyperelasticity (TB,AHYPER), and userswstrain is supported by the swelling strain-function model (TB,SWELL).
For more information, see Material Model Support for Elements and Element Support for Material Models in the Element Reference.
You can combine various user subroutines for material customization and use them together. Following are the valid combinations supported:
| UserMat | UserCreep | userthstrain | userswstrain | user_tbelastic | UserHyper | UserHyperAniso | userMullins | UsrShift | |
| UserMat | ✔ | ✔ | |||||||
| UserCreep | ✔ | ✔ | ✔ | ||||||
| userthstrain | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| userswstrain | ✔ | ✔ | ✔ | ✔ | |||||
| user_tbelastic | ✔ | ✔ | ✔ | ||||||
| UserHyper | ✔ | ✔ | ✔ | ||||||
| UserHyperAniso | ✔ | ✔ | ✔ | ||||||
| userMullins | ✔ | ✔ | ✔ | ✔ | |||||
| UsrShift | ✔ | ✔ | ✔ | ✔ |
For porous media analysis, the subroutine
userfreestrain (to
define the free-strain increment) can be combined with other subroutines if the native
material of those subroutines is supported by coupled
pore-pressure-thermal mechanical elements (CPTnnn),
as in this example:
You can use state variables with material subroutine combinations.
User-defined state variables (TB,STATE) are supported by a number of subroutines that customize material behavior. The following topics are available:
The following subroutines support the use of user-defined state variables:
| Subroutine | Purpose |
|---|---|
| UserMat | Creating your own material model |
| UserMatTh | Creating your own thermal material model |
| UserHyper | Writing your own isotropic hyperelasticity laws |
| UserHyperAniso | Writing your own anisotropic hyperelasticity laws |
| userMullins | Writing your own pseudo-elastic Mullins Effect law |
| UserCreep | Defining your own implicit creep material behavior |
| UserCr | Defining your own explicit creep material behavior |
| userCZM | Creating your own cohesive zone material |
| user_tbelastic | Defining your own material linear elastic properties |
| userswstrain | Defining your own swelling laws |
| userthstrain | Defining your own thermal strain |
| userfreestrain | Defining your own free-strain increment |
| UsrShift | Calculating a pseudotime time increment according to a user-specified shift function |
Depending on the subroutine, a user-defined state variable is passed into the subroutine as an argument, or retrieved and updated via API calls:
State variables are passed directly into some subroutines, such as UserMat and UserCreep, as arguments.
The program updates the state variable to its final state and updates the database automatically.
In other subroutines, such as userthstrain and user_tbelastic, state variables are retrieved via an API call (get_ElmData).
When a state variable is retrieved via an API, it must be updated to its final state via an API call (put_ElmData). Doing so updates the database with the current value of the state variable.
Example 4.44: State Variable Passed in as an Argument
In this example, the user-defined state variable name is
Ustatev. It is passed directly into UserCreep, a
subroutine that enables you to define your own creep material behavior.
*deck,UserCreep USERDISTRIB parallel
SUBROUTINE UserCreep (impflg, ldstep, isubst, matId , elemId,
& kDInPt, kLayer, kSecPt, nstatv, nprop,
& prop , time , dtime , temp , dtemp ,
& toffst, Ustatev, creqv , pres , seqv ,
& delcr , dcrda)
c*******************************************************************
Example 4.45: State Variables Retrieved and Updated via API Calls
In this example, the subroutine in which state variables are being retrieved and updated is userthstrain, which enables you to define your own thermal strain.
*deck,userthstrain USERDISTRIB parallel optimize
subroutine userthstrain (nprop, propv,
& ncomp, epth)
c … code …
c --- get element info
call get_ElmInfo ('ELEMID ',elemId)
call get_ElmInfo ('MATIPT ',matipt)
call get_ElmInfo ('NSVAR ', nstatev)
c *** Retrieve state variable
call get_ElmData ('SVAR', elemId, matipt, nstatev, statev)
c … code …
c *** Update state variable to database
call put_ElmData ('SVAR', elemId, matipt, nstatev, statev)
You can use state variables with subroutine combinations. For a given material, the state variable array length is defined via TB,STATE. The subroutines in a combination share the same state variable array.
Track State Variable Indices
Because each subroutine in a combination can have separate state variables, keep track of the state variable indices used for each subroutine. For example, the first subroutine may use indices 1 to 6, the second one may use indices 7 to 15, and so on.
Understand the Subroutine Calling Order
When it is necessary to share information via state variables between subroutines, in addition tracking the indices, be aware of the calling order of the subroutines. The various routines are called in a specific predefined order independent of user definitions and input. The calling order is hard-coded and adheres to the preexisting code framework.
One option to determine the calling order is to include write statements in the
subroutines and examine the output file. For example, write(6,*) "Here in
subroutine UserMat."
Another option is to use one of the state variable locations to indicate which routine was called previously. You can do so by assigning arbitrary numbers to the subroutines and inspecting the state variable value to learn the order. When combining userthstrain + UserMat, for example, the calling order is 1) userthstrain, then 2) UserMat. The order is intuitive because thermal strain is calculated and subtracted from the total strain before the material subroutine is called.
Subroutines May Be Called More Than Once
In a given global Newton-Raphson iteration, at a given material integration point, some subroutines may be called more than once depending on the element formulation. For example, due to the iterative nature of the hyperelasticity algorithm for plane stress, UserHyper can be called multiple times while the plane stress algorithm tries to converge. Subroutines called more than once can also lead to each material integration point having a different number of subroutine calls to satisfy convergence.