2.4. Subroutines for Customizing Material Behavior

This section describes the following subroutines that you can use to modify or monitor material behavior:

Using the “_MATL” String

If you write a material-behavior subroutine using the MPDATA, MPDELE, TB, or TBDELE command, be aware that when the string "_MATL" appears in the MAT field of the command, the command interprets the string to mean the currently active material (as defined via the MAT,MAT command).

The "_MATL" string is used in conjunction with the library (LIB) option of the MPREAD and MPWRITE commands. When you issue MPWRITE with the LIB option, the command inserts "_MATL" in lieu of the specified material number as these commands are written to the material library file. When the program reads a material library file written in this format, it interprets "_MATL" to mean the currently active material. Do not use the "_MATL" string outside the scope of the MPREAD command.

2.4.1. Subroutine UserMat (Creating Your Own Material Model)

The UserMat subroutine allows you to write your own material constitutive equations within a general material framework using current-technology elements.

UserMat is a tool for advanced users. Expertise in material constitutive modeling and software programming is necessary. Developing a custom material constitutive model requires validation and testing. ANSYS, Inc. strongly recommends testing both single elements and multiple elements with various loading conditions to ensure correct results. UserMat supports shared memory and distributed parallel processing; however, you are responsible for ensuring that your code can use parallel processing.

For a UserMat subroutine example, see Appendix C: User Material (UserMat) Subroutine Example.

2.4.1.1. UserMat Overview

The UserMat subroutine defines the material stress-strain relationship of a material and applies to any analysis procedure involving mechanical behavior. The subroutine supports current-technology elements only and does not apply to legacy elements.

The subroutine is called at every material integration point of the elements during the solution phase. The program passes in stresses, strains, and state variable values at the beginning of the time increment and strain increment at the current increment, then updates the stresses and state variables to the appropriate values at the end of the time increment.

The two most important UserMat-calculated quantities are stress and the consistent tangent stiffness:

  • The measure of the stress is Cauchy stress (true stress), .

  • The consistent tangent stiffness is defined as , where is the stress increment and is the strain increment. The measure of strain is logarithmic strain (true strain), .

Generally, the material model can be formulated in either incremental (rate) or total forms.

  • The incremental form is suitable for material models such as plasticity. The program uses a co-rotated framework for such material formulation. All variables are defined and updated in the co-rotated material coordinate system. The implementation of a constitutive model looks exactly the same for both small and large deformation (NLGEOM,ON).

  • The total form is commonly used with hyperelastic material, and the material response is characterized by a potential relating to the invariants of the deformation gradient. The discrete equations are formulated with respect to the reference configuration. The deformation gradient is defined in the global coordinate system (with the exception of shell elements, where the deformation gradient is expressed on the co-rotated element coordinate system).

For most of the hyper-elastic models, material behavior is considered to be incompressible or nearly incompressible, resulting in a singular element matrix and possibly leading to element volumetric locking and solution failure. It is therefore necessary to take measures to avoid the singularity. The penalty method of carefully selecting the penalty parameter (which is also the compressibility parameter) is the simplest approach. Elements with mixed u-P formulation are the best way to address the singularity caused by material incompressibility. To use this option, set TBOPT = MXUP and element KEYOPT(6) = 1.

For a user-defined material with purely incompressible behavior, a mixed formulation in which the pressure is a degree of freedom is necessary. When a nearly incompressible hyperelastic material is formulated in UserMat, additional information (derivatives of volumetric potential with regard to determinant of deformation gradient J) is required. For more information, see UserMat Variables .

Input values and the number of state variables (if used) for UserMat are specified via the TB command. For more information, see Table (TB) Commands for UserMat.

Further Reading

ANSYS, Inc. recommends the following resource to help you understand how user-defined materials are implemented:

Hughes, Thomas J.R. and James Winget. “Finite Rotation Effects in Numerical Integration of Rate Constitutive Equations Arising in Large-Deformation Analysis.” [International Journal for Numerical Methods in Engineering]. 15.9 (1980): 1413-1418.

2.4.1.2. Stress, Strain, and Material Jacobian Matrix

The stress measure (σ) used by the subroutine is the Cauchy stress (true stress), and the strain measure (ε) is the logarithmic strain (true strain). The strains and incremental strains passed into UserMat are the total mechanical strains from which the thermal strains (if they exist) are subtracted.

UserMat must also provide the material Jacobian matrix defined as . is the stress increment, and is the strain increment.

UserMat is based on the current configuration for nonlinear geometry analysis (NLGEOM,ON). The program uses a co-rotational approach to account for rigid body rotation. Because the program already accounts for the strains passed into UserMat for the rigid body rotation, there is no need to apply additional rotation within UserMat.

Stress, strain, and the material Jacobian tensors are stored in a vector or matrix format.

The order of components for all tensors is as follows:

3-D stress state

11, 22, 33, 12, 23, 13

2-D plane strain and axisymmetric stress states

11, 22, 33, 12

2-D plane stress states

11, 22, 12

Beam element stress states

11, 13, 12

Link element stress state

11

The order of components for the material Jacobian matrix is as follows:

3-D stress state
111111221133111211231113
221122222233221222232213
331133223333331233233313
121112221233121212231213
231123222333231223232313
131113221333131213231313
2-D plane strain and axisymmetric stress states
1111112211331112
2211222222332212
3311332233333312
1211122212331212
2-D plane stress states
111111221112
221122222212
121112221212
Beam element stress states
111111131112
131113131312
121112131212
Link element stress state
1111

2.4.1.3. The UserMat API

Following is the interface for the UserMat subroutine:

*deck,usermat                      USERSDISTRIB
      subroutine usermat(
     &                   matId, elemId,kDomIntPt, kLayer, kSectPt,
     &                   ldstep,isubst,keycut,
     &                   nDirect,nShear,ncomp,nStatev,nProp,
     &                   Time,dTime,Temp,dTemp,
     &                   stress,ustatev,dsdePl,sedEl,sedPl,epseq,
     &                   Strain,dStrain, epsPl, prop, coords, 
     &                   var0, defGrad_t, defGrad,
     &                   tsstif, epsZZ,
     &                   var1, var2, var3, var4, var5,
     &                   var6, var7, var8)
c*************************************************************************
c     *** primary function ***
c
c           user defined material constitutive model
c
c      Attention:
c           User must define material constitutive law properly
c           according to the stress state such as 3D, plane strain
c           and axisymmetry, plane stress and 3D/1D beam.
c
c           a 3D material constitutive model can use for
c           plane strain and axisymmetry cases.
c
c           When using shell elements, a plane stress algorithm
c           must be use.
c
c                                             gal July, 1999
c
c       The following demonstrates a USERMAT subroutine for 
c       a plasticity model, which is the same as TB, BISO,
c       for different stress states. 
c       See "ANSYS user material subroutine USERMAT" for detailed
c       description of how to write a USERMAT routine.
c
c       This routine calls four routines,
c       usermat3d.F, usermatps.F usermatbm.F and usermat1d.F, w.r.t.
c       the corresponding stress states.
c       Each routine can be also a usermat routine for the specific 
c       element.
c
c*************************************************************************
c
c     input arguments
c     ===============
c      matId     (int,sc,i)               material #
c      elemId    (int,sc,i)               element #
c      kDomIntPt (int,sc,i)               "k"th domain integration point
c      kLayer    (int,sc,i)               "k"th layer
c      kSectPt   (int,sc,i)               "k"th Section point
c      ldstep    (int,sc,i)               load step number
c      isubst    (int,sc,i)               substep number
c      nDirect   (int,sc,in)              # of direct components
c      nShear    (int,sc,in)              # of shear components
c      ncomp     (int,sc,in)              nDirect + nShear
c      nstatev   (int,sc,l)               Number of state variables
c      nProp     (int,sc,l)               Number of material ocnstants
c
c      Temp      (dp,sc,in)               temperature at beginning of
c                                         time increment
c      dTemp     (dp,sc,in)               temperature increment 
c      Time      (dp,sc,in)               time at beginning of increment (t)
c      dTime     (dp,sc,in)               current time increment (dt)
c
c      Strain   (dp,ar(ncomp),i)          Strain at beginning of time increment
c      dStrain  (dp,ar(ncomp),i)          Strain increment
c      prop     (dp,ar(nprop),i)          Material constants defined by TB,USER
c      coords   (dp,ar(3),i)              current coordinates
c      defGrad_t(dp,ar(3,3),i)            Deformation gradient at time t
c      defGrad  (dp,ar(3,3),i)            Deformation gradient at time t+dt
c
c     input output arguments              
c     ======================             
c      stress   (dp,ar(nTesn),io)         stress
c      ustatev   (dp,ar(nstatev),io)      user state variables
c      sedEl    (dp,sc,io)                elastic work
c      sedPl    (dp,sc,io)                plastic work
c      epseq    (dp,sc,io)                equivalent plastic strain
c      tsstif   (dp,ar(2),io)             transverse shear stiffness
c                                         tsstif(1) - Gxz
c                                         tsstif(2) - Gyz
c                                         tsstif(1) is also used to calculate hourglass
c                                         stiffness, this value must be defined when low
c                                         order element, such as 181, 182, 185 with uniform 
c                                         integration is used.
c      var?     (dp,sc,io)                not used, they are reserved arguments 
c                                         for further development
c
c     output arguments
c     ================
c      keycut   (int,sc,io)               loading bisect/cut control
c                                         0 - no bisect/cut
c                                         1 - bisect/cut 
c                                         (factor will be determined by ANSYS solution control)
c      dsdePl   (dp,ar(ncomp,ncomp),io)   material jacobian matrix
c      epsZZ    (dp,sc,o)                 strain epsZZ for plane stress,
c                                         define it when accounting for thickness change
c                                         in shell and plane stress states
c
c*************************************************************************
c
c      ncomp   6   for 3D  (nshear=3)
c      ncomp   4   for plane strain or axisymmetric (nShear = 1)
c      ncomp   3   for plane stress (nShear = 1)
c      ncomp   3   for 3d beam      (nShear = 2)
c      ncomp   1   for 1D (nShear = 0)
c
c      stresss and strains, plastic strain vectors
c          11, 22, 33, 12, 23, 13    for 3D
c          11, 22, 33, 12            for plane strain or axisymmetry
c          11, 22, 12                for plane stress
c          11, 13, 12                for 3d beam
c          11                        for 1D
c
c      material jacobian matrix
c        3D
c           dsdePl    |  1111   1122   1133   1112   1123   1113 |
c           dsdePl    |  2211   2222   2233   2212   2223   2213 |
c           dsdePl    |  3311   3322   3333   3312   3323   3313 |
c           dsdePl    |  1211   1222   1233   1212   1223   1213 |
c           dsdePl    |  2311   2322   2333   2312   2323   2313 |
c           dsdePl    |  1311   1322   1333   1312   1323   1313 |
c        plane strain or axisymmetric (11, 22, 33, 12)
c           dsdePl    |  1111   1122   1133   1112 |
c           dsdePl    |  2211   2222   2233   2212 |
c           dsdePl    |  3311   3322   3333   3312 |
c           dsdePl    |  1211   1222   1233   1212 |
c        plane stress (11, 22, 12)
c           dsdePl    |  1111   1122   1112 |
c           dsdePl    |  2211   2222   2212 |
c           dsdePl    |  1211   1222   1212 |
c        3d beam (11, 13, 12)
c           dsdePl    |  1111   1113   1112 |
c           dsdePl    |  1311   1313   1312 |
c           dsdePl    |  1211   1213   1212 |
c        1d
c           dsdePl    |  1111 |
c
c*************************************************************************

2.4.1.4. UserMat Variables

The UserMat subroutine uses the following Input, Input/Output, and Output variables. Do not change them in the subroutine code.

UserMat Input Arguments
matIdInteger variable containing the material ID number.
elemIdInteger variable containing the element number.
kDomIntPtInteger variable containing the material integration point number.
kLayerInteger variable containing the layer number.
kSectPtInteger variable containing section point number.
ldstepInteger variable containing load step number.
isubstInteger variable containing substep number.
nDirectNumber of direct components of the stress or strain vector at material point.
nShearNumber of shear components of the stress or strain vector at material point (engineering components).
ncompTotal number of the stress or strain components at material point (nDirect + nShear).
nstatevNumber of state variables, specified by the NPTS value in the TB,STATE command.
nPropNumber of material constants, specified by the NPTS value in the TB,USER command.
TempDouble-precision variable containing the current temperature.
dTempDouble-precision variable containing the current temperature increment.
TimeDouble-precision variable containing the total time at the beginning of the time increment.
dTimeDouble-precision variable containing the current time increment.
Strain

Double-precision array containing the total strains at the beginning of the time increment. Array size is ncomp.

Thermal strains (defined via MP,ALPHA and temperature load), if any, are subtracted from the total strains; therefore, the strains passed to UserMat are the mechanical strains only.

For large-deformation problems, (NLGEOM,ON), the strain components are updated to account for rigid body rotation before they are passed to UserMat and are approximately the logarithmic strains.

When the mixed u-P formulation option (TBOPT = MXUP on the TB,USER command) is used for hyperelastic material, the strain array is the logarithmic strains at the current time. However, the strain array can be redefined within the UserMat subroutine. For nearly incompressible hyperelastic material, a mixed u-J formulation is used. The calculated J is passed from strain array as strain(ncomp+1).

dStrain

Double-precision array containing current strain increments. Array size is ncomp. As with the Strain array, this value contains the mechanical strain increments only. Thermal strain increments (if any) are subtracted from the total strains increments.

When the mixed u-P formulation option (TBOPT = MXUP on the TB,USER command) is used for hyperelastic material, the dStrain array is zero.

propDouble-precision array containing the material constants defined via TB,USER and TBDATA commands. Array size is nProp. Array prop contains the material constants at current temperature point.
coordsDouble-precision array containing the current coordinates of the material integration points. Array size is 3.
defGrad_tDouble-precision matrix containing deformation gradient at the beginning of the time increment. The matrix size is 3 x 3. The matrix components DefGrad_t(i,j) are equivalent to deformation gradient Fij at the beginning of the time increment and are only available for continuum and shell elements with nonlinear deformation (NLGEOM,ON).
defGradDouble-precision matrix containing current deformation gradient. The matrix size is 3 x 3. The matrix components DefGrad(i,j) are equivalent to deformation gradient Fij at the current time and are only available for continuum and shell elements with nonlinear deformation (NLGEOM,ON).
UserMat Input/Output Arguments
stress

Double-precision array containing the stresses. Its size is defined by the ncomp input value. The stress measure is the "true" stress. It is passed as the values of stresses at the beginning of the time increment and must be updated to the values of stress at the end of the time increment.

For finite-deformation problems, the stresses are rotated to account for rigid body motion before they are passed in, and thus only the co-rotational portion of stress integration is required in UserMat.

When the mixed u-P formulation option (TBOPT = MXUP on the TB,USER command) is used for hyperelastic material, the stress is updated for deviatoric part of stress only. The calculated P is passed into usermat as stress(ncomp+1).

statev

Double-precision array containing the state variables. Its size is defined via the TB,STATE command. It is passed as the values of state variables at the beginning of the time increment and must be updated to the values of the state variables at the end of the time increment.

epseqEquivalent plastic strain.
epspl

Double-precision array containing the plastic strains. The strain measure is the "true" strain. Its size is defined by the ncomp input value. It is passed as the values of the plastic strains at the beginning of the time increment and must be updated to the values of the plastic strains at the end of the time increment.

For finite-deformation problems, the plastic strains have been rotated to account for rigid body motion before they are passed in.

sedElElastic work. It is used for output purposes only and does not affect the solution.
sedPlPlastic work. It is used for output purposes only and does not affect the solution.
UserMat Output Arguments

These values must be updated in the subroutine code.

keycut

Integer variable as key for loading bisection/cut control:

0 - No bisect/cut (default)
1 - Bisect/cut

Set keycut = 1 when UserMat experiences convergence difficulty when solving constitutive equation integration. The bisect/cut factor is determined by the solution control. Set cutFactor to control the time stepping size.

epsZZStrain component at an out-of-plane direction for the plane stress state. This value is required when the thickness change is taken into account in plane stress or shell elements.
tsstif(2)

Transverse shear stiffness:

Tsstif(1) - GXZ
Tsstif(2) - GYZ
dsdePl(ncomp,ncomp)

Double-precision array containing the material Jacobian matrix . Here, the values represent the stress/strain increments, respectively. The dsdePl(i,j) value denotes the change in the i-th stress component at the end of the time increment caused by a change of the j-th strain component.

By default, the program assumes that the element stiffness matrix is symmetric; therefore, you must provide a symmetric material Jacobian matrix even if it is unsymmetric. If your material requires an unsymmetric material Jacobian matrix, issue the NROPT,UNSYM command to define the unsymmetric stiffness matrix.

When the mixed u-P formulation option (TBOPT = MXUP on the TB,USER command) is used for hyperelastic material, only the deviatoric material consistent tangent matrix is needed.

pVolDer(:)

Derivatives of volumetric potential with regard to the determinant of deformation gradient:

pVolDer(1) =

pVolDer(2) =

pVolDer(3) =

This argument is needed only when a hyperelastic material is defined and mixed u-P formulation is used.

For nearly incompressible hyperelastic material, a mixed u-J formulation is used. The derivatives of volume potential is to Jc, where Jc is the calculated J and is passed from strain array as strain(ncomp+1).

For purely incompressible hyperelastic material, set all three derivatives pVolDer(1:3) to zero.

cutFactorTime-step size control factor.

2.4.1.5. Table (TB) Commands for UserMat

When creating your own material model, first define the material by specifying input values for the UserMat subroutine (TB,USER). It is also necessary to specify the number of state variables used, if applicable (TB,STATE).

Following is more information about defining your material and specifying the number of state variables used. For detailed information about the TB command and arguments, see the Command Reference.

TB,USER Command

Issue the TB command using the following syntax:

TB,USER,MAT,NTEMPS,NPTS,TBOPT

where

MAT = User material ID number

NTEMPS = Number of temperature points.

NPTS = Number of material constants at a given temperature point.

TBOPT = NONLINEAR (default), LINEAR, or MXUP

The material properties at an intermediate temperature point are interpolated and passed to the UserMat subroutine.

Define temperatures and material constants via TBTEMP and TBDATA commands, respectively.

Example 2.1:  Defining the Material for UserMat
tb,user,1,2,4                    ! Define material 1 as a user 
                                 ! material with two temperatures
                                 ! and four data points at each 
                                 ! temperature point.
tbtemp,1.0                       ! first temp. 
tbdata,1,19e5, 0.3, 1e3,100,	    ! Four mat. constants for one temp.
tbtemp,2.0                       ! Second temp.
tbdata,1,21e5, 0.3, 2e3,100,     ! Four mat. constants for two temps.

TB,STATE Command

If you intend to use state variables with the UserMat subroutine, it is necessary to first specify the number of state variables. Issue the TB command using the following syntax:

TB,STATE,MAT, ,NPTS

where

MAT = User material ID number

NPTS = Number of state variables that you intend to use.

The command defines only the number of state variables and must always be associated with a user material ID. No temperatures or data are associated with the command.

By default, the program initializes state variables to zero at the beginning of an analysis. Use the TBDATA command to initialize your own values for state variables.

Example 2.2:  Defining the Number of State Variables for UserMat
tb,state,1,,8                         ! Define material 1 with eight state variables
tbdata,1,c1,c2,c3,c4,c5,c6,c7,c8      ! Initialize the eight state variables.

2.4.1.6. Material Constitutive Integration with UserMat

The UserMat subroutine supports current-technology elements with all key options. However, a different material constitutive integration is necessary for the various stress states, such as general 3-D, plane stress, and beam (with or without shear-stress components).

To ensure overall numerical stability, verify that the integration scheme implemented in the subroutine is stable. The program always uses the full Newton-Raphson scheme for the global solution to achieve a better convergence rate. The material Jacobian matrix (dsdePl(i,j)) must be consistent with the material constitutive integration scheme for a better convergence rate of the overall Newton-Raphson scheme.

2.4.1.7. UserMat Restrictions

The following restrictions apply to the UserMat subroutine:

  • The subroutine supports current-technology elements only and does not apply to legacy elements.

    For more information, see Legacy vs. Current Element Technologies in the Element Reference.

  • The state variables (defined via the TB,STATE command) are supported only by full graphics in the POST1 postprocessor.

    Because POST1 does not switch to full graphics automatically, you must issue a /GRAPHICS,FULL command to do so.

  • The UserMat interface for elements with mixed u-P formulation is supported only for current-technology continuum elements (such as PLANE182, PLANE183, SOLID185, SOLID186, SOLID187, SOLSH190, CPT212, CPT213, CPT215, CPT216 and CPT217), excluding plane stress state. KEYOPT(6) = 1 is required. For elements with a plane stress assumption, a mixed u-P formulation is not needed.

  • The deformation gradient defGrad(3,3) and defGrad_t(3,3) are available only for continuum and shell elements with nonlinear deformation (NLGEOM,ON).

2.4.1.8. Accessing Material and Element Data for UserMat

Following is the interface for accessing the material and element data :

get_ElmData (inquire, elemId, kIntg, nvect, vect)

c --- argument list
 
      CHARACTER*4           inquire
      INTEGER               elemId, kIntg, nvect
      DOUBLE PRECISION      vect(nvect)

c        definition
c           inquire        - query argument (string, see variables)
c           elemId         - element number
c           kIntg          - gauss intg. number
c           nvect          - number of vector to be inquired
c           vect           - vector to be inquired
get_ElmData Input Arguments
inquireString variable containing a query argument.
elemIdInteger variable containing the element number.
kDomIntPtInteger variable containing the material integration point number.
nvectInteger variable containing number of variable to be retrieved.
Vect(*)Variable array containing the retrieved variables.
Valid inquire Argument Variables
ESYSElement coordinate system (ESYS).
ISIGInitial stress.
TREFReference temperature.

2.4.1.9. Utility Functions for UserMat

The following functions are available for use with UserMat. ANSYS, Inc. provides them for your convenience.

Utility Functions for UserMat

vzero( a ,n)

Initializes array a to zero.

The value n is the array dimension.

vmult( a , b ,n,c)

Multiplies vector a by constant c and outputs ( b = a * c) as vector b .

The value n is the dimension for both arrays.

vmult1( a ,n,c)

Multiplies vector a by constant c and outputs the result as itself (that is, a = a * c).

The value n represents the array dimension.

maxb( a , b , c , na, nb, nc, n1, n2, n3)

Multiplies two double-precision matrices and outputs the result as c (that is, c = a * b ).

The value na is number of rows in matrix a , nb the number of rows in matrix b , and nc the number of rows in matrix c .

The n1 value is the number of rows in matrix c to fill, and n2 the number of columns in matrix c to fill.

The value n3 is the number of columns in matrix a and the number of rows in matrix b to work with. (The number of columns in a and rows in b is the same in order to generate the inner product correctly.)

2.4.2. Subroutine UserMatTh (Creating Your Own Thermal Material Model)

UserMatTh is a tool for advanced users. Expertise in thermal material modeling and software programming is necessary. Developing a custom thermal material model requires validation and testing. ANSYS, Inc. strongly recommends testing both single elements and multiple elements with various loading conditions to ensure correct results. UserMatTh supports shared memory and distributed parallel processing; however, you are responsible for ensuring that your code can use parallel processing.

2.4.2.1. UserMatTh Element Support

The UserMatTh subroutine is available for current-technology elements SOLID278 and SOLID279. It is also available for FLUID116 with KEYOPT(1) = 1.

UserMatTh is called at every material integration point of the elements during the solution phase.

Input values and the number of state variables (if used) for the subroutine are specified via the TB command. For more information, see Table (TB) Commands for UserMatTh.

2.4.2.2. The UserMatTh API

Following is the interface for the UserMatTh subroutine:

*deck,usermatth      USERDISTRIB  parallel
      subroutine usermatth(matId, elemId, kDomIntPt, kLayer, kSectPt,
     &                     ldstep, isubst, keycut, ncomp, nStatev,nProp,
     &                     Time, dTime, Temp, dTemp, tgrad, 
     &                     ustatev, prop, coords, 
     &                     dudt,dudg,flux,dfdt,dfdg, 
     &                     cutFactor,hgen, dens, var1, var2, var3,
     &                     var4, var5, var6)
c*************************************************************************
c     *** primary function ***
c
c           user defined thermal material constitutive model
c
c     Attention:
c           User must define material constitutive behavior properly
c
c
c       The following demonstrates a USERMATTH subroutine for 
c       a regular conductive heat transfer.
c       See "ANSYS user material subroutine USERMATTH" for detailed
c       description of how to write a USERMATTH routine.
c
c
c*************************************************************************
c Copyright ANSYS.  All Rights Reserved.
c
c     input arguments
c     ===============
c      matId     (int,sc,i)               material #
c      elemId    (int,sc,i)               element #
c      kDomIntPt (int,sc,i)               "k"th domain integration point
c      kLayer    (int,sc,i)               "k"th layer
c      kSectPt   (int,sc,i)               "k"th Section point
c      ldstep    (int,sc,i)               load step number
c      isubst    (int,sc,i)               substep number
c      ncomp     (int,sc,i)               # of components
c      nStatev   (int,sc,i)               Number of state variables
c      nProp     (int,sc,i)               Number of material constants
c
c      Temp      (dp,sc,in)               current temperature
c      dTemp     (dp,sc,in)               temperature increment  
c      Time      (dp,sc,in)               time at beginning of increment (t)
c      dTime     (dp,sc,in)               current time increment (dt)
c
c      prop      (dp,ar(nprop),i)         Material constants defined by TB,USER
c      coords    (dp,ar(3),i)             current coordinates
c
c      tgrad     (dp,ar(ncomp),i)         Current values of the spatial gradients of temperature
c
c
c     input output arguments              
c     ======================             
c      ustatev   (dp,ar(nstatev),io)      user state variables
c      hgen      (dp,sr,io)               heat generation rate per unit mass
c      dens      (dp,sr,io)               density passed in as defined by mp command
c      var?      (dp,sc,io)               not used, they are reserved arguments 
c                                         for further development
c
c     output arguments
c     ================
c      keycut    (int,sc,o)               loading bisect/cut control
c                                         0 - no bisect/cut
c                                         1 - bisect/cut
c                                         (factor will be determined by ANSYS solution control)
c 
c      cutFactor (dp,sc,o)                time step size cut-back factor
c                                         define it if a smaller step size is wished 
c                                         recommended value is 0~1
c
c      dudt      (dp,sr,o)                unit mass internal energy variation with respect to 
c                                         temperature      
c      dudg      (dp,ar(ncomp),o)         unit mass internal thermal energy variation  with 
c                                         respect to the spatial gradients of temperature
c      flux      (dp,ar(ncomp),o)         heat flux vector      
c      dfdt      (dp,ar(ncomp),o)         heat flux vector variation with respect to temperature
c      dfdg      (dp,ar(ncomp,ncomp),o)   heat flux vector variation with respect to the spatial 
c                                         gradients of temperature
c
c*************************************************************************
c
c      ncomp   3   for 3D
c      ncomp   2   for 2D
c      ncomp   1   for 1D
c
c
c*************************************************************************

2.4.2.3. UserMatTh Variables

The UserMatTh subroutine uses the following Input, Input/Output, and Output variables. Do not change them in the subroutine code.

UserMatTh Input Arguments
matIdInteger variable containing the material ID number.
elemIdInteger variable containing the element number.
kDomIntPtInteger variable containing the material integration point number.
kLayerInteger variable containing the layer number.
kSectPtInteger variable containing section point number.
ldstepInteger variable containing load step number.
isubstInteger variable containing substep number.
ncompInteger variable containing spatial dimension number: 1 for 1-D, 2 for 2-D, or 3 for 3-D.
nStatevNumber of state variables, specified via the NPTS value in the TB,STATE command.
nPropNumber of material constants, specified via the NPTS value in the TB,USER command.
TempDouble-precision variable containing the current temperature.
dTempDouble-precision variable containing the current temperature increment.
TimeDouble-precision variable containing the total time at the beginning of the time increment.
dTimeDouble-precision variable containing the current time increment.
propDouble-precision array containing the material constants defined via TB,USER and TBDATA commands. Array size is nProp. Array prop contains the material constants at current temperature point.
coordsDouble-precision array containing the current coordinates of the material integration points. Array size is 3.
tgradDouble-precision array of size ncomp containing temperature gradient at the beginning of the time increment.
UserMatTh Input/Output Arguments
hgenDouble-precision variable with heat-generation information. It is passed in as the value that is predefined with the model. The value can be updated with user-defined heat generation.
ustatev

Double-precision array containing the state variables. Its size is defined via the TB,STATE command. It is passed as the values of state variables at the beginning of the time increment and must be updated to the values of the state variables at the end of the time increment.

densDouble precision variable with density information. It is passed in as the value that is predefined with the model. The value can be updated with user-defined density.
UserMatTh Output Arguments

These values must be updated in the subroutine code.

keycut

Integer variable as key for loading bisection/cut control:

0 - No bisect/cut (default)
1 - Bisect/cut

Set keycut = 1 when UserMatTh experiences convergence difficulty when solving constitutive equation integration. The bisect/cut factor is determined by the solution control.

cutFactorDouble-precision variable containing the user-defined time-step size-control factor.
dudtDouble-precision variable containing the unit mass internal energy variation with respect to temperature.
dudgDouble-precision array of size (ncomp,ncomp) containing the unit mass internal thermal energy variation with respect to the spatial gradients of temperature.
fluxDouble-precision array of size ncomp containing the heat flux vector.
dfdtDouble-precision array of size ncomp containing the heat flux vector variation with respect to temperature.
dfdgDouble-precision array of size (ncomp,ncomp) containing the heat flux vector variation with respect to the spatial gradients of temperature.

2.4.2.4. Table (TB) Commands for UserMatTh

When creating your own material model, first define the material by specifying input values for the UserMatTh subroutine (TB,USER). It is also necessary to specify the number of state variables used, if applicable (TB,STATE).

Following is more information about defining your material and specifying the number of state variables used. For detailed information about the TB command and arguments, see the Command Reference.

TB,USER Command

Issue the TB command using the following syntax:

TB,USER,MAT,NTEMPS,NPTS,TBOPT

where

MAT = User material ID number

NTEMPS = Number of temperature points.

NPTS = Number of material constants at a given temperature point.

TBOPT = NONLINEAR (default) or LINEAR

The material properties at an intermediate temperature point are interpolated and passed to the UserMatTh subroutine.

Define temperatures and material constants via TBTEMP and TBDATA commands, respectively.

Example 2.3:  Defining the Material for UserMatTh
tb,user,1,2,4                  ! Define material 1 as a user
                               ! material with two temperatures
                               ! and four data points at each
                               ! temperature point
tbtemp,1.0                     ! first temperature 
tbdata,1,19e5,0.3,1e3,100,     ! four material constants for
                               ! one temperature
tbtemp,2.0                     ! Second temperature
tbdata,1,21e5,0.3,2e3,100,     ! Four material constants for 
                               ! two temperatures

TB,STATE Command

If you intend to use state variables with the UserMatTh subroutine, it is necessary to first specify the number of state variables. Issue the TB command using the following syntax:

TB,STATE,MAT, ,NPTS

where

MAT = User material ID number.

NPTS = Number of state variables that you intend to use.

The command defines only the number of state variables and must always be associated with a user material ID. No temperatures or data are associated with the command.

By default, the program initializes state variables to zero at the beginning of an analysis. Use the TBDATA command to initialize your own values for state variables.

2.4.2.5. UserMatTh Restrictions

The following restrictions apply to the UserMatTh subroutine:

  • The subroutine supports current-technology elements only and does not apply to legacy elements. For more information, see UserMatTh Element Support.

  • The state variables (defined via the TB,STATE command) are supported only by full graphics in the POST1 postprocessor.

    Because POST1 does not switch to full graphics automatically, you must issue a /GRAPHICS,FULL command to do so.

  • Element FLUID116 is supported only when KEYOPT(1) = 1. For this element, you can use UserMatTh to specify material properties KXX, C, and DENS only.

2.4.2.6. Utility Functions for UserMatTh

The following functions are available for use with UserMatTh. ANSYS, Inc. provides them for your convenience.

Utility Functions for UserMatTh

vzero( a ,n)

Initializes array a to zero.

The value n is the array dimension.

vmult( a , b ,n,c)

Multiplies vector a by constant c and outputs ( b = a * c) as vector b .

The value n is the dimension for both arrays.

vmult1( a ,n,c)

Multiplies vector a by constant c and outputs the result as itself (that is, a = a * c).

The value n represents the array dimension.

maxb( a , b , c , na, nb, nc, n1, n2, n3)

Multiplies two double-precision matrices and outputs the result as c (that is, c = a * b ).

The value na is number of rows in matrix a , nb the number of rows in matrix b , and nc the number of rows in matrix c .

The n1 value is the number of rows in matrix c to fill, and n2 the number of columns in matrix c to fill.

The value n3 is the number of columns in matrix a and the number of rows in matrix b to work with. (The number of columns in a and rows in b is the same in order to generate the inner product correctly.)

2.4.3. Subroutine UserHyper (Writing Your Own Hyperelasticity Laws)

Use the subroutine UserHyper when you issue the TB command with the HYPER option, and with the command option TBOPT = 100.

*deck,UserHyper                      USERSDISTRIB
c Copyright ANSYS.  All Rights Reserved.
      subroutine UserHyper(
     &                      prophy, incomp, nprophy, invar,
     &                      potential, pInvDer)
c************************************************************************
c
c     *** Example of user hyperelastic routine
c
c           This example uses Arruda hyperelasticity model
c           which is the same ANSYS TB,BOYCE
c
c     input arguments
c     ===============
c      prophy       (dp,ar(*),i)     material property array
c      nprophy     (int,sc,i)        # of material constants
c      invar       dp,ar(3)          invariants
c
c     output arguments
c     ================
c      incomp      (log,sc,i)         fully incompressible or compressible
c      potential    dp,sc             value of potential
c      pInvDer       dp,ar(10)        der of potential wrt i1,i2,j
c                                      1 - der of potential wrt i1
c                                      2 - der of potential wrt i2
c                                      3 - der of potential wrt i1i1
c                                      4 - der of potential wrt i1i2
c                                      5 - der of potential wrt i2i2
c                                      6 - der of potential wrt i1j
c                                      7 - der of potential wrt i2j
c                                      8 - der of potential wrt j
c                                      9 - der of potential wrt jj
c
c************************************************************************
c
c --- parameters
c

2.4.4. Subroutine UserCreep (Defining Creep Material Behavior)

Use the subroutine UserCreep to define creep material behavior. The subroutine is applicable when you issue the TB command with the CREEP option, and with TBOPT = 100.

UserCreep supports shared memory and distributed parallel processing; however, you are responsible for ensuring that your code can use parallel processing.

The subroutine is called at all integration points of elements for which the material is defined by this command. The program always uses implicit time integration for this creep option. You can use plasticity options (BISO, BKIN, NLISO, PLASTIC) to define the plastic behavior of materials. Creep and plastic strain are calculated simultaneously when both creep and plasticity are defined for a material.

Using this subroutine, you can specify a "uniaxial" creep law that will be generalized to the multi-axial state by the general time-dependent viscoplastic material formulation implemented in the program. You can use and update internal state variables in the subroutine. The number of state variables must be defined (TB,STATE).

Please see the TB command description for more information.

*deck,usercreep                      USERSDISTRIB
      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*************************************************************************
c     *** primary function ***
c           Define creep laws when creep table options are
c           TB,CREEP with TBOPT=100.
c           Demonstrate how to implement usercreep subroutine 
c
c            Creep equation is 
c               dotcreq := k0 * seqv ^ n * creqv ^ m * exp (-b/T)
c
c               seqv  is equivalent effective stress (Von-Mises stress)
c               creqv is equivalent effective creep strain
c               T     is the temperature
c               k0, m, n, b are materials constants,
c
c           This model corresponds to  primary creep function  TBOPT = 1
c
c                                                          gal 10.01.1998
c
c*************************************************************************
c Copyright ANSYS.  All Rights Reserved.
c
c     input arguments
c     ===============
c      impflg   (in ,sc   ,i)             Explicit/implicit integration 
c                                         flag (currently not used)
c      ldstep   (in ,sc   ,i)             Current load step
c      isubst   (in ,sc   ,i)             Current sub step 
c      matId    (in ,sc   ,i)             number of material index
c      elemId   (in ,sc   ,i)             Element number
c      kDInPt   (in ,sc   ,i)             Material integration point
c      kLayer   (in ,sc   ,i)             Layer number
c      kSecPt   (in ,sc   ,i)             Section point
c      nstatv   (in ,sc   ,i)             Number of state variables
c      nprop    (in ,sc   ,i)             size of mat properties array    
c
c      prop     (dp ,ar(*),i)             mat properties array    
c                                         This array is passed all the creep
c                                         constants defined by command
c                                         TBDATA associated with TB,CREEP
c                                         (do not use prop(13), as it is used 
c                                         elsewhere)
c                                         at temperature temp.
c      time                               Current time
c      dtime                              Current time increment
c      temp                               Current temperature
c      dtemp                              Current temperature increment
c      toffst   (dp, sc,   i)             temperature offset from absolute zero
c      seqv     (dp ,sc  , i)             equivalent effective stress
c      creqv    (dp ,sc  , i)             equivalent effective creep strain
c      pres     (dp ,sc  , i)             hydrostatic pressure stress, -(Sxx+Syy+Szz)/3
c                                         note that: constitutive consistency is not accounted for
c                                         if creep strains are function of pressure 
c
c     input output arguments              input desc     / output desc
c     ======================              ==========       ===========
c      Ustatev  (dp,ar(*), i/o)           user defined iinternal state variables at 
c                                         time 't' / 't+dt'.
c                                         This array will be passed in containing the 
c                                         values of these variables at start of the 
c                                         time increment. They must be updated in this
c                                         subroutine to their values at the end of 
c                                         time increment, if any of these internal 
c                                         state variables are associated with the 
c                                         creep behavior.
c
c     output arguments
c     ================
c      delcr    (dp ,sc  , o)             incremental creep strain
c      dcrda    (dp,ar(*), o)             output array
c                                         dcrda(1) - derivitive of incremental creep 
c                                                    strain to effective stress
c                                         dcrda(2) - derivitive of incremental creep 
c                                                    strain to creep strain
c
c     local variables
c     ===============
c      c1,c2,c3,c4 (dp, sc, l)            temporary variables as creep constants 
c      con1        (dp ,sc, l)            temporary variable
c      t           (dp ,sc, l)            temporary variable
c
c*************************************************************************
c
c --- parameters
c

2.4.5. Subroutine user_tbelastic (Defining Material Linear Elastic Properties)

Subroutine user_tbelastic provides an interface for defining your own material linear elastic properties (TB,ELASTIC). The following topics are available:

2.4.5.1. Overview of the user_tbelastic Subroutine

The user_tbelastic subroutine can define material linear elastic properties as a function of temperature or coordinates. The subroutine is called at the material integration points of elements for which the definition of material elastic properties is a user option. The material properties defined are based on the material coordinate system of the elements.

You can use the subroutine with most current-technology elements and with most nonlinear material models.

For more information about these material models, see the documentation for the TB command in the Command Reference.

2.4.5.2. Data Types Supported by user_tbelastic

The user_tbelastic subroutine can define the following types of material property data:

  • Isotropic elasticity with two constants

    Define the Young's modulus (EX) and Poisson’s ratio (NUXY) material constants

  • General orthotropic elasticity with nine constants

    Define the normal modulus, shear modulus, and minor Poisson’s ratios. The order is as follows: EX, EY, EZ, GXY, GXZ, GYZ, NUXY, NUXZ, NUYZ. All nine constants must be defined; no default values are assigned.

  • Anisotropic elasticity with 21 constants

    Define the material elastic stiffness matrix. The matrix consists of 21 constants, and all must be defined.

2.4.5.3. Table (TB) Command for user_tbelastic

Issue a TB command using the following syntax to access the user_tbelastic subroutine interface:

TB,ELASTIC,mat,,npts,USER

The ELASTIC argument accesses the elastic material property data table. (For more information, see the documentation for the TB command's ELASTIC option in the Command Reference.)

The mat value represents the material number, and the npts value is the number of material constants.

The USER argument accesses the interface to the user_tbelastic subroutine.

2.4.5.4. User Interface for user_tbelastic

The user_tbelastic interface consists of six arguments, as follows:

  • Four input arguments for the element number, material number, coordinate array, and temperature

  • One input/output argument for the number of material constants

  • One output argument consisting of the material constants array

The syntax is as follows: SUBROUTINE user_tbelastic(elemId, matId, coords, temp, nprop, prop)

Argument Input (I) or Output (O) Definition
elemId IElement number
matId IMaterial number
coords ICoordinates of material integration point at initial configuration (geometry)
temp ICurrent temperature at material integration point
nprop I / O

Number of constants to be returned (input) or actually returned (output), as follows:

2 - isotropic elasticity
9 - orthotropic elasticity
21 - anisotropic elasticity

The value for this argument is obtained via the TB,ELASTIC command, and is passed into the subroutine. However, you can redefine this value in the subroutine, which then returns it.

prop OThe material elastic constants to be defined

2.4.5.5. The user_tbelastic API

Following is the interface to the user_tbelastic subroutine:

*deck,user_tbelastic                      USERSDISTRIB
      SUBROUTINE user_tbelastic(elemId, matId, coords, temp,
     &                          nprop,  prop)
c*************************************************************************
c     *** primary function ***
c           user interface for elastic material constants
c
c*************************************************************************
c Copyright ANSYS.  All Rights Reserved.
c
c     input arguments
c     ===============
c      elemId   (in, sc   , i)    Element number
c      matId    (in, sc   , i)    Number of material index
c      temp     (dp, sc   , i)    Current temperature
c
c      coords   (dp, ar(5), i)    Coordinates at initial configuration      
c                                  For continuum elements:
c                                   1-3:  coordinates of integration point 
c                                   4-5:  not used
c                                  For line elements:
c                                   1-3:  coordinates of integration point
c                                            along line member axis
c                                   4-5:  offsets in element y and z directions
c
c      output arguments              
c     ======================              
c      nprop    (in, sc   , o)    Number of constants
c                                    2  - isotropic   elasticity
c                                    9  - orthotropic elasticity
c                                    21 - anisotropic elasticity
c      prop     (dp, ar(*), o)    Material elastic constants (stiffness)

c     local variables
c     ===============
c
c*************************************************************************
c
c --- parameters
c

2.4.5.6. Usage Example for user_tbelastic

In this example, three elements in parallel are subjected to uniaxial tension.

Element 1 is a SOLID185 element defined via the MP command with linear isotropic elasticity.

Element 2 is a SOLID185 element defined via the user-defined elastic material properties interface.

Element 3 is a SHELL181 element defined via the user-defined elastic material properties interface.

Solid elements are a unit cubic with a 1 mm edge. The shell element is a unit square with a 1 mm edge. The Young's modulus is 210E6 MPa, and the Poisson’s ratio is 0.3.

Example Input

/batch
/com
/com example for user elastic material property interface
/com
/com element 1 solid185 defined via standard MP command
/com element 2 solid185 defined using ansys elastic material interface
/com element 3 shell181 defined using ansys elastic material interface
/com
/prep7

esize,,1
et,1,185
et,2,181

mp,ex,1,210e6
mp,nuxy,1,0.3
tb,elastic,2,1,2,user   ! user-defined elastic material interface

! SOLID185 element
mat,2
block,,1,,1,,1
vmesh,1
mat,1
block,,1,,1,,1
vmesh,2

! SHELL181 element
sectype,1,shell
secdata, 0.100000,1
secdata, 0.100000,2
rect,,1,,1
secn,1
mat,2
type,2
amesh,1

elist,all,all

nsel,s,loc,x
d,all,ux
nsel,s,loc,y
d,all,uy
nsel,s,loc,z
d,all,uz

/solu

nsel,s,loc,x,1
d,all,ux,0.05
alls
solve

fini
/post1
set,1
pres,s
pres,epel
fini

2.4.6. Subroutine userfc (Defining Your Own Failure Criteria)

*deck,userfc                      USERSDISTRIB
      subroutine userfc (elem,matlay,iott,tem,elim,slim,
     x                   eps, sig, nfcOut, fc)
c     primary function: user subroutine for defining your own failure criterion
c *** secondary functions: none
c
c *** user programmable functions may not be used in parallel processing ***
c     this is currently only available with
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     variable (typ,siz,intent)    description
c     elem     (int,sc,in)       - element number
c     elim     (dp,ar(9),in)     - failure strains at the current temperature
c                                   (see FC command input with Lab1 = EPEL)
c     slim     (dp,ar(12),in)    - failure stresses and coupling coefficients
c                                   at the current temperature
c                                   (see FC command input with Lab1 = S)
c     eps      (dp,ar(6),in)     - vector of strains
c     sig      (dp,ar(6),in)     - vector of stresses
c     tem      (dp,sc,in)        - temperature at this point in the model
c     matlay   (int,sc,in)       - material number
c     iott     (int,sc,in)       - unit number for writing
c
c  output arguments:
c     variable (typ,siz,intent)    description
c     nfcOut   (int,sc, out)      - number of user fc computed 
c     fc       (dp,ar(9),out)    - user failure criterion
c

2.4.7. Subroutine userCZM (Defining Your Own Cohesive Zone Material)

Define your own interfacial cohesive material law via the TB,CZM,,,,USER command.

Issue the TBDATA command to define the material constants. Data may be temperature-dependent and is interpolated at the current temperature of the material integration point and passed to the subroutine.

For more information, see User-Defined Cohesive Material (UserCZM) and Using State Variables with the UserCZM Subroutine in the Material Reference.

Following is the user cohesive material interface:

*deck,userCZM                      USERSDISTRIB
      subroutine userCZM (matId, elemId, kMatIntPt, ldstep,isubst,
     &                    keycut, ncomp,nProp, nstatev,
     &                    Time, dTime, Temp, dTemp,
     &                    coords, prop, Strain, dStrain, 
     &                    stress, dsdePl, sedEl, sedPl, statev,
     &                    var1, var2, var3, var4, var5)
c
c*************************************************************************
c
c     *** primary function ***
c
c           user cohesive zone model example
c
c           Commands
c             TB,CZM,mat,NTEMP,NPTS,user 
c                TBTEMP if mat. constants are temperature dependent
c                TBDATA define material constants
c
c*************************************************************************
c
c     input arguments
c     ===============
c      matId     (int,sc,in)              material #
c      elemId    (int,sc,in)              element #
c      kMatIntPt (int,sc,in)              material integration point #
c      ldstep    (int,sc,in)              load step number
c      isubst    (int,sc,in)              substep number
c      ncomp     (int,sc,in)              number of stress, strain components
c      nProp     (int,sc,in)              Number of material ocnstants
c      nstatev   (int,sc,in)              Number of state variables
c
c      Temp      (dp ,sc,in)              temperature at beginning of time increment
c      dTemp     (dp ,sc,in)              temperature increment 
c      Time      (dp ,sc,in)              time at beginning of increment (t)
c      dTime     (dp ,sc,in)              time increment (dt)
c
c      prop     (dp,ar(nprop),i)          Material constants defined by TB command 
c      Strain   (dp,ar(ncomp),i)          Interface separation at beginning of time increment
c      dStrain  (dp,ar(ncomp),i)          Interface separation increment
c      coords   (dp,ar(3),i)              current coordinates
c
c     output arguments              
c     ======================             
c      stress   (dp,ar(nTesn),io)         Traction stress
c      sedEl    (dp,sc,io)                elastic work
c      sedPl    (dp,sc,io)                plastic work
c      keycut   (int,sc,io)               loading bisect/cut control
c                                         0 - no bisect/cut
c                                         1 - bisect/cut 
c                                         (factor will be determined by ANSYS solution control)
c      dsdePl   (dp,ar(ncomp,ncomp),io)   consistent tangent jacobian matrix
c
c     input output arguments              
c     ======================             
c      statev   (dp,ar(nstatev,io)        user defined solution state variables
c
c     misc.
c     ======================             
c      var1, var2, var3, var4, var5       currently not used
c
c     local variables
c     ======================             
c
c      debugflag (in,sc, l)                debugflag to print debug information
c
c
c*************************************************************************
c

2.4.8. Subroutine userswstrain (Defining Your Own Swelling Laws)

You can define your own swelling strain option via the TB,SWELL,,,,USER command.

Use the TBDATA command to define the material constants. Data may be temperature-dependent and is interpolated at the current temperature of the material integration point and passed to the subroutine.

For more information, see Swelling in the Material Reference.

*deck,userswstrain  USERDISTRIB
      subroutine userswstrain  (elemId,  kMatPoint
     &,                         matId,   nprop,   propv
     &,                         time,    dtime
     &,                         efvs,    defv
     &,                         sweqt,   dsweq
     &,                         swvi,    swvo)
c
c
c *** primary function:    compute user defined swelling strain
c
c *** Notice - This file contains ANSYS Confidential information ***
c Copyright ANSYS.  All Rights Reserved.
c
c  input arguments:
c     matId    (int,sc,in)       - material #
c     elemId   (int,sc,in)       - element  #
c     kMatPoint(int,sc,in)       - element integration point #
c     nprop    (int,sc,in)       - number of material constants
c     time     (int,sc,in)       - current time
c     dtime    (int,sc,in)       - current time increment
c     propv    (dp,ar(nprop),in) - array of material constants
c                                  (the data input via TBDATA command)
c     efvs     (dp,ar(*)    ,in) - field variables array
c                                  efvs(1) - current temperature
c                                  efvs(2) - current fluence
c     defv     (dp,ar(*)    ,in) - incremental field variables array
c                                  defv(1) - temperature increment
c                                  defv(2) - fluence increment
c     sweqt    (dp,sc       ,in) - equivalent swelling strain at time t
c
c  output arguments:
c     dsweq    (dp,sc       ,in) - incremental equivalent swelling strain
c  not used arguments:
c     swvi     (dp,sc       ,in) - not currently used
c     swvo     (dp,sc       ,in) - not currently used
c
c****************************************************************
c

2.4.9. Subroutine userck (Checking User-Defined Material Data)

*deck,userck                      USERSDISTRIB
      subroutine userck (curmat,ntb,tb)
c *** primary function:    check the user-defined material data,
c                           input with the TB,user command.
c *** secondary functions:  none
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     curmat   (int,sc,in)       - current material number
c     ntb      (int,sc,in)       - dimension of tb
c     tb       (dp,ar(ntb),in)   - input table
c
c  output arguments:
c     none
c

2.4.10. Supporting Function egen

The function egen (kcomp,ep,nuxy) (function) combines kcomp strain components (ep) per:

*deck,egen
      function egen (kcomp,ep,posn)
c primary function:    combines strain components to give an "overall" strain
c                      used in creep and plasticity calculations
c secondary functions: none

c    formulation of overall value is by:

c         ___________________________________________________________________
c        /1             2             2             2  1    2      2      2 
c    \  / -*((ep  - ep ) + (ep  - ep ) + (ep  - ep ) + -*(ep   + ep   + ep ))
c     \/  2     1     2       2     3       3     1    2   4      5      6  
c    ------------------------------------------------------------------------
c                                (1 + posn)

c *** Notice - This file contains ANSYS Confidential information ***
                                                                     
c     typ=int,dp,log,chr,dcp   siz=sc,ar(n)   intent=in,out,inout
                                                                 
c  input arguments:
c     variable (typ,siz,intent)    description
c     kcomp    (int,sc,in)       - number of components of strain
c     ep       (dp,ar(6),in)     - the strain components
c     posn     (dp,sc,in)        - poisson's ratio
                                             
c  output arguments:
c     egen     (dp,func,out)     - the combined strain value
c

2.4.11. Subroutine userfld (Update User-Defined Field Variables)

You can create your own field variables using via the INISTATE command and supported materials (TB). Node-based initial state helps to initialize the user-defined field variables that are then used by the TB database to evaluate the material properties at an integration point. userfld allows you to examine the current state at the integration point and to modify the field variables as needed.

For more information, see Understanding Field Variables in the Material Reference.

*deck,userfld                      USERSDISTRIB
      subroutine userfld
     &          ( matId, elemId,
     &            ldstep, isubst, time, dtime,
     &            kDomIntPt, kLayer, kSectPt,
     &            nDirect, nShear, nComp, nStatev,
     &            coords,
     &            Temp,dTemp )
c*************************************************************************
c     *** primary function ***
c
c           Edit Field Variables During Solution
c
c      Attention:
c
c*************************************************************************
c Copyright ANSYS.  All Rights Reserved.
c
c     input arguments
c     ===============
c      matId     (int,sc,i)               material #
c      elemId    (int,sc,i)               element #
c      ldstep    (int,sc,i)               load step num
c      isubst    (int,sc,i)               substep num
c      time      (int,sc,d)               time
c      dtime     (int,sc,d)               time inc
c      kDomIntPt (int,sc,i)               "k"th domain integration point
c      kLayer    (int,sc,i)               "k"th layer
c      kSectPt   (int,sc,i)               "k"th Section point
c      nDirect   (int,sc,in)              # of direct components
c      nShear    (int,sc,in)              # of shear components
c      ncomp     (int,sc,in)              nDirect + nShear
c      nstatev   (int,sc,i)               Number of state variables
c      Temp      (dp,sc,in)               temperature at beginning of
c                                         time increment
c      dTemp     (dp,sc,in)               temperature increment 
c      coords   (dp,ar(3),i)              current coordinates
c
c     input output arguments              
c     ======================             
c
c
c     output arguments
c     ================
c
c*************************************************************************
c                        List of Supported Field Variable Types
c*************************************************************************
c
c     FLD_USER_1_TYPE  
c     FLD_USER_2_TYPE  
c     FLD_USER_3_TYPE  
c     FLD_USER_4_TYPE  
c     FLD_USER_5_TYPE  
c     FLD_USER_6_TYPE  
c     FLD_USER_7_TYPE  
c     FLD_USER_8_TYPE  
c     FLD_USER_9_TYPE  
c
c*************************************************************************

2.4.12. Subroutine userthstrain (Defining Your Own Thermal Strain)

You can define the thermal strain via the TB,CTE,,,,USER command and the userthstrain subroutine.

Issue the TBDATA command to define the material constants. Data can be field-dependent, and is interpolated at the current field values of the material integration point and passed to the subroutine.

For more information, see Thermal Expansion in the Mechanical APDL Material Reference.

*deck,userthstrain  USERDISTRIB
      subroutine userthstrain (nprop, propv,
     &                         ncomp, epth)
c
c *** primary function:    compute the thermal strain
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     nprop    (int,sc,in)       - number of material constants
c     propv    (dp,ar(ncomp),in) - array of material constants
c                                  e.g. coefficients of thermal
c                                       expansion in x,y,z order
c     ncomp    (int,sc,in)       - number of strain components
c                                  6  for 3-d elements   (x,y,z,xy,yz,xz)
c                                  4  for plane elements (x,y,z,xy)
c                                  3  for beam elements  (x,xy,xz)
c                                  1  for line elements  (x)
c
c  output arguments:
c     epth    (dp,ar(ncomp),out) - thermal strains 
c


Release 18.2 - © ANSYS, Inc. All rights reserved.