2.4. Subroutines for Customizing Material Behavior

The following subroutines enable you to create your own material models, or to modify or monitor material behavior:

Using the "_MATL" String

If you write a material-behavior subroutine via MPDATA, MPDELE, TB, or TBDELE, 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 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.

State Variable Support

Many material-behavior subroutines support the use of user-defined state variables, as indicated in the description for a given subroutine. For more information, see Using State Variables with Material Subroutines in the Material Reference.

 

2.4.1. Subroutine UserMat (Creating Your Own Material Model)

The UserMat subroutine enables 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.

The following UserMat topics are available:

For a UserMat subroutine example, see Appendix C: User Material (UserMat) Subroutine Example. For an example of UserMat in a coupled-field analysis, see Appendix D: Structural-Thermal User Material (UserMat, UserMatTh) Example.

 

2.4.1.1. UserMat Element Support

Element support for user-defined material models (TB,USER) is available in Material Model Support for Elements in the Material Reference.

 

2.4.1.2. UserMat Overview

The UserMat subroutine defines the material stress-strain relationship of a material and applies to time-domain and full-harmonic analysis types. 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 increment (and for time-domain analyses, the strain increment at the current increment). The UserMat subroutine then updates the stresses and state variables to current values.

 
2.4.1.2.1. Time Domain

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.

 
2.4.1.2.2. Harmonic

For full-harmonic analyses, the incoming strain argument is a two-dimensional vector containing the real (material stiffness) and imaginary (damping) parts of the harmonic strain. The subroutine must calculate and return the real and imaginary parts of the stress and material Jacobian matrix for the current frequency.

The complex stress returned by the subroutine has no effect on the harmonic solution and is used for postprocessing only.

 

2.4.1.3. Stress, Strain, and Material Jacobian Matrix

For nonlinear geometry analysis, 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:

3D stress state

11, 22, 33, 12, 23, 13

2D plane strain and axisymmetric stress states

11, 22, 33, 12

2D 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:

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

2.4.1.4. The UserMat API

Following is the interface for the UserMat subroutine:

*deck,usermat                      USERDISTRIB
      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,
     &                   cutFactor, pVolDer, hrmflg, var3, var4,
     &                   var5, var6, var7)
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 be used for
c           plane strain and axisymmetry cases.
c
c           When using shell elements, a plane stress algorithm
c           must be used.
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 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      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      nProp     (int,sc,i)               Number of material constants
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      hrmflg   (dp,sc,io)                flag to indicate harmonic analysis 
c
c     input output arguments              
c     ======================             
c      stress   (dp,ar(ncomp),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      epsPl   (dp,ar(ncomp),io)          plastic strain
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 solution control)
c      dsdePl   (dp,ar(ncomp,ncomp),o)    material jacobian matrix
c      pVolDer  (dp,ar(3),o)              derivatives of volumetric potential wrt to J
c                                         pVolDer(1) = dU/dJ
c                                         pVolDer(2) = d^2U/dJ^2
c                                         pVolDer(3) = d^3U/dJ^3
c      tsstif   (dp,ar(2),o)              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      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      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*************************************************************************
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      stresses 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*************************************************************************

The ncomp value used in get_ElmData and put_ElmData may differ from the ncomp value passed into usermat.F. Use get_ElmData with the 'NCOMP' option to determine the correct array sizes.

 

2.4.1.5. 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 temperature at the beginning of time increment.
dTempDouble-precision variable containing the current temperature increment.
TimeFor time-domain analyses, a double-precision variable containing the total time at the beginning of the time increment. For full-harmonic analyses, the current value of frequency.
dTimeFor time-domain analyses, a double-precision variable containing the current time increment. For full-harmonic analyses, the frequency increment.
Strain

Double-precision array containing the total strains at the beginning of the time increment. Array size is Strain(ncomp) in time-domain analyses and Strain(ncomp,2) in harmonic analyses, where the real and imaginary strain components are in the first and second column, respectively.

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.

For time-domain analyses, 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 harmonic analyses, its size is stress(ncomp,2), where the first column is the real stress and the second column is the imaginary stress.

For finite-deformation problems, the stresses are rotated to account for rigid body motion before they are passed in, and therefore 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.

Not used in harmonic analyses.

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

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 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.

For harmonic analyses, the real components are returned in dsdePl(1:ncomp,1:ncomp,1), and the imaginary components are returned in dsdePl(1:ncomp,1:ncomp,2).

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.

cutFactor

Time-step size control factor.

Not used in harmonic analyses.

 

2.4.1.6. 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).

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.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

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, 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 (maximum 1000).

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.7. 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 3D, 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 time-domain 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.8. UserMat Restrictions

The following restrictions apply to the UserMat subroutine:

 

2.4.1.9. Accessing Material and Element Data for UserMat

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

*deck,get_ElmData
      subroutine get_ElmData (kchar, elemId, kMatRecPt, ncomp, vect)
c
c*************************************************************************
c
c     *** primary function
c            retrieve material record data
c            including items:
c                stress vector
c                elastic strain vector
c                plastic strain vector
c                creep   strain vector
c                thermal strain vector
c                state variables
c
c                                       ---- Guoyu Lin 4/25/2001 ----
c
c**************************************************************************
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c Note: To keep documentation and code consistent, any changes made in the 
c header comments of this subroutine MUST ALSO BE COPIED to userOut.F. 
c This is required because this internal routine has no USERDISTRIB 
c command, is not distributed to the installation media, and its headers 
c are not automatically copied to the documentation.
c
c     input arguments
c     ===============
c     kchar         (ch,sc,in)        string characters indicating 
c                                     inquired quantities
c     kMatRecPt     (in,sc,in)        integration point where data 
c                                     to be inquired
c     elemId        (in,sc,in)        element number
c     ncomp         (in,sc,in)        number of components to be inquired
c                                     Use the 'NCOMP' query to get the right 
c                                     size for tensor quantities.
c     numWordsPt    (in,ar(*),in)     number of mat. Record
c
c     input output arguments         input desc     / output desc
c     ======================         ==========       ===========
c
c     output arguments
c     ================
c     vect          (dp,ar(*),ou)     inquired data
c
c     local variables
c     ===============
c
c*************************************************************************

c --- parameters
c

The ncomp value used in get_ElmData and put_ElmData may differ from the ncomp value passed into usermat.F. Use get_ElmData with the NCOMP option to determine the correct array sizes.

For a descriptions of the input arguments and valid argument variables, see Accessing Solution and Material Data.

 

2.4.1.10. 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.

The following UserMatTh topics are available:

 

2.4.2.1. UserMatTh Element Support

Element support for user-defined thermal material models (TB,USER) is available in Material Model Support for Elements in the Material Reference.

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 TB. 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
      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)               temperature at current time 
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 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   3   for 2D ( third component of dudg, tgrad, flux, dft
c                           must be set to 0.d0 . Also third row/column
c                           of dfdg matrix must be set to 0.d0 )
c      ncomp   3   for 1D ( second and third component of dudg, tgrad, flux, dft
c                           must be set to 0.d0 . Also second and third row/column
c                           of dfdg matrix must be set to 0.d0 )
c
c
c*************************************************************************
 

2.4.2.3. UserMatTh Variables

The UserMatTh subroutine uses the following Input, Input/Output, and Output variables. Do not change the Input arguments 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 1D, 2 for 2D, or 3 for 3D.
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 current temperature gradient.
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. [1]
ustatevDouble-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.[1]
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.[1]

  1. In a coupled structural-thermal analysis using SOLID225, SOLID226 and SOLID227:

    • the heat generation rate (hgen) is interpreted as heat flow rate per unit volume,

    • the state variables (ustatev) cannot be updated with user-defined values in UserMatTh,

    • the density (dens) cannot be updated with user-defined value in UserMatTh.

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).

In a coupled-field analysis with structural and thermal degrees of freedom, use TB,USER with TBOPT = THERM to define the thermal material independently of the structural material model. The THERM option is available with elements SOLID225, SOLID226 and SOLID227.

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 THERM

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

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

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

For an example of UserMatTh in a coupled-field analysis, see Appendix D: Structural-Thermal User Material (UserMat, UserMatTh) Example.

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 (maximum 1000).

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 Isotropic Hyperelasticity Laws)

Use the subroutine UserHyper when you issue TB,HYPER with TBOPT = USER.

The last material property determines the material compressibility setting. If it is , the material is set to incompressible; otherwise it is set to compressible. The compressibility setting affects the automatic element key option selection and the mixed u-P formulation. The setting should match the compressibility behavior of the strain energy potential.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

*deck,UserHyper                      USERDISTRIB
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,HYPER,,,,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 UserHyperAniso (Writing Your Own Anisotropic Hyperelasticity Laws)

The UserHyperAniso subroutine defines the potential derivatives for a strain-energy potential that is a function of isochoric strain invariants and anisotropic fiber invariants.

 

2.4.4.1. Input Parameters

Use the UserHyperAniso subroutine when you issue TB,AHYPER with TBOPT = USER.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

Issue TBDATA to specify the invariant set type (SetType). The only valid set type is 101, which defines the invariant set as the isochoric strain invariants and isochoric fiber invariants defined below.

Example 2.4: User-Defined Anisotropic Hyperelastic Material Model

/prep7
TB,AHYPER,1,,,USER
TBDATA,1,101        ! define the invariant set type

You can define an optional set number (SetNumber) in a data table initiated via TBOPT = UNUM. This value is passed into the subroutine for use in distinguishing between user-defined material behaviors.

Example 2.5: User-Defined Anisotropic Hyperelastic Set Number

/prep7
TB,AHYPER,1,,,UNUM
TBDATA,1,1          ! define the invariant set number

Define the material parameters in a table initiated via TBOPT = AU01.

Example 2.6: User-Defined Anisotropic Hyperelastic Parameters

/prep7
TB,AHYPER,1,,,AU01
 !a1, a2, a3
    tbdata,1,a1
 !b1, b2, b3
    tbdata,4,b1
 !c1, c2, c3,
    tbdata,7,c1, c2, c3,
 !d2, d3, d4, d5, d6
    tbdata,12,0,0.0,0.0,0.0,0.0
 !e1, e2, e3
    tbdata,17,e1, e2, e3
 !f1, f2, f3, f4, f5, f6
    tbdata,22,0,0.0,0.0,0.0,0.0
 !g1, g2, g3, g4, g5, g6
    tbdata,27,0,0.0,0.0,0.0,0.0
 !d
    tbdata,31,1e-5

Specify the fiber directions in a data table with TBOPT = FB01. Three values define the direction of a fiber. The direction is relative to the element coordinate system and should have a magnitude equal to 1.0. The number of fibers (25 maximum) is determined from the number of defined values.

Example 2.7: User-Defined Anisotropic Hyperelastic Fiber Directions

/prep7
TB,AHYPER,1,,,FB01
TBDATA,1,1,0,0
TBDATA,4,1/sqrt(2),1/sqrt(2),0

 

2.4.4.2. Invariants and Potential Derivatives

Define the strain-energy potential as a function of the isochoric strain invariants and the anisotropic invariants that depend on the fiber directions and deformation.

where are the isochoric strain invariants and are the fiber directions. The strain-energy potential depends on isochoric fiber invariants that have the form:

where is a first-order fiber invariant, is a second-order fiber invariant, and is a mixed-fiber variant.

Mixed second-order fiber invariants are not used in the strain-energy potential definition.

The isochoric strain invariants are numbered 1, 2, and 3 respectively in the Invar(*) array. The fiber-invariant numbering scheme is obtained from the following function:

ni = FIindx(SetType,InvType,Fib1,Fib2)

where:

ni = returned value of invariant number in Invar(*) array
SetType = set type passed into UserHyperAniso
InvType = invariant type: 1 = first-order, 2 = second-order
Fib1 = first fiber number, i
Fib2 = second fiber number, i or j

The UserHyperAniso subroutine should calculate and return the first and second derivatives of the user-defined strain-energy potential with respect to the invariants. For mixed u-P formulations that are not incompressible, the third-order invariant with respect to is also required. (Third-order derivatives of the strain-energy potential with respect to other invariants are not required.)

The compressibility of the material is determined from the second derivative of the strain-energy potential with respect to in the reference configuration during the first solution step. If this derivative is zero, the material is incompressible and the appropriate mixed u-P formulation is used. The material should not change between compressible and incompressible behavior during the simulation.

The strain-energy-potential derivatives are stored in the arrays pD1(*), pD2(*) and pD3(*) via the following subroutine:

put_PDer(SetType,nFib,Order,In1,In2,In3,pD1,pD2,pD3,val)

where:

SetType = set type passed into UserHyperAniso
nFib = number of fibers passed into UserHyperAniso
Order = derivative order to be stored (1, 2, or 3)
In1, In2, In3 = invariant numbers corresponding to the respective derivatives
pD1, pD2, pD3 = potential derivative arrays passed into UserHyperAniso
val = value of the derivative that is added to the value in the array
 

2.4.4.3. UserHyperAniso API

*deck,UserHyperAniso                      USERDISTRIB
      subroutine UserHyperAniso(SetType,SetNumber,incomp,upkey,nprophy,
     &                     prophy,nFib,fibDir,ninv,Invar,potential,
     &                     pD1,pD2,pD3)
c************************************************************************
c
c     *** Example of user anisotropic hyperelastic routine
c
c           This example reproduces the Polynomial hyperelasticity 
c          model which is the same as TB,AHYPER,,,,POLY
c
c     input arguments
c     ===============
c      SetType     (int,sc,i)        Type of invariant set
c      SetNumber   (int,sc,i)        User input invariant set number
c      incomp      (log,sc,i)        incompressibility flag (.true. for incompressible) 
c      upkey       (int,sc,i)        mixed uP key (/=0 for mixed uP formulation)
c      nprophy     (int,sc,i)        number of prophy values
c      prophy      (dp,ar(*),i)      material property array
c      nFib        (int,sc,i)        number of fibers
c      invar       dp,ar(3)          invariants
c      fibDir      (dp,ar(3,*),i)    original fiber directions array
c      ninv        (int,sc,i)        number of invariants
c      Invar       (dp,ar(*),i)      set of Invariants
c
c     output arguments
c     ================
c      potential    dp,sc             value of potential
c      pD1       dp,ar(*)             1st derivatives of potential wrt Invar(*)
c      pD2       dp,ar(*)             2nd derivatives of potential wrt Invar(*)
c      pD3       dp,ar(*)             3rd derivatives of potential wrt J
c
c************************************************************************
 

2.4.5. Subroutine userMullins (Writing Your Own Pseudo-Elastic Mullins Effect Law)

Use the subroutine userMullins when you issue TB,CDM with TBOPT = MUSER.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

For more information, see Mullins Effect (TB,CDM) in the Material Reference and Mullins Effect Model in the Structural Analysis Guide.

*deck,userMullins                      USERDISTRIB
      subroutine userMullins(W,Wmax,eta,deta,nProp,prop,
     x                       nStatev,ustatev)
c****************************************************************
c
c *** primary function:    User routine for pseudo elastic mullins effect
c
c *** Notice - This file contains ANSYS Confidential information ***
c Copyright ANSYS.  All Rights Reserved.
c
c  input arguments:
c     W        (dp,sc,in)        - current strain energy potential 
c     Wmax     (dp,sc,in)        - maximum strain energy potential
c     nProp    (int,sc,in)       - number of material constants
c     prop     (dp,ar(nProp),in) - array of material constants
c     nStatev  (int,sc,in)       - Number of state variables
c
c  output arguments:
c     eta      (dp,sc,out)         - stress scaling value
c     deta     (dp,sc,out)         - d eta / d W
c     ustatev  (dp,ar(nstatev),io) -  user state variables
c
c****************************************************************
 

2.4.6. Subroutine UserCreep (Defining Your Own Implicit Creep Material Behavior)

Use the subroutine UserCreep to define creep material behavior. The subroutine applies when issuing TB,CREEP 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 generalized to the multi-axial state via the program's general time-dependent viscoplastic material formulation.

You can use and update internal state variables in the subroutine. Specify the number of state variables via TB,STATE.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

*deck,usercreep                      USERDISTRIB
      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 accumulated equivalent 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)             accumulated equivalent 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      expt        (dp ,sc, l)            temporary variable
c      t           (dp ,sc, l)            temporary variable
c
c*************************************************************************
c
c --- parameters
c
 

2.4.7. Subroutine UserCr (Defining Your Own Explicit Creep Material Behavior)

Use the subroutine UserCr to define creep material behavior. The subroutine applies when issuing TB,CREEP with TBOPT = 0 and defining constant C6 = 100 via TBDATA.

UserCr supports shared memory and distributed parallel processing, but you must ensure that your code can use parallel processing.

The subroutine is called at all integration points of elements for which the material is defined. The program always uses explicit time integration for this creep option. You can use plasticity options (BISO, BKIN, PLASTIC) to define the plastic behavior of materials. Creep and plastic strain are calculated using non-simultaneous modeling (superposition) when both creep and plasticity are defined for a material. In such cases, the program first performs the plastic analysis, then the creep calculation.

You can use UserCr to specify a uniaxial creep law generalized to the multi-axial state via the program's general time-dependent viscoplastic material formulation.

You can use and update internal state variables in the subroutine. Specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference. 

*deck,usercr                      USERDISTRIB
      subroutine usercr (elem,intpt,mat,ncomp,kfirst,kfsteq,e,posn,d,
     x proptb,timval,timinc,tem,dtem,toffst,fluen,dfluen,epel,epcrp,
     x statev,var1,delcr)
c
c *** primary function:   allow users to write their own creep laws.
c                           this logic is accessed with c6 = 100
c *** secondary function:    demonstrate the use of user-written creep laws
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c
c         *** Copyright ANSYS.  All Rights Reserved.
c         *** ansys, inc.
c
c  input arguments:
c     variable (type,sze,intent)    description
c
c     elem     (int,sc,in)         - element number (label)
c     intpt    (int,sc,in)         - element integration point number
c     mat      (int,sc,in)         - material reference number
c     ncomp    (int,sc,in)         - no. of stress/strain components (1,4 or 6)
c                                    1 - x
c                                    4 - x,y,z,xy
c                                    6 - x,y,z,xy,yz,xz
c     kfirst   (int,sc,in)         - 1 if first time through, 0 otherwise
c     kfsteq   (int,sc,in)         - 1 if first equilibrium iteration of a
c                                    substep, 0 otherwise
c
c
c     e        (dp,sc,in)          - elastic young'S MODULUS
c     posn     (dp,sc,in)          - poisson'S RATIO
c     d        (dp,ar(ncomp,ncomp),in)- elastic stress-strain matrix
c     proptb   (dp,ar(72),in)      - material properties input on tb commands
c                               (do not use proptb(13), as it is used elsewhere)
c     timval   (dp,sc,in)          - current time value
c     timinc   (dp,sc,in)          - time increment over this substep
c     tem      (dp,sc,in)          - temperature at the end of this substep
c     dtem     (dp,sc,in)          - temperature increment over this substep
c     toffst   (dp,sc,in)          - temperature offset from absolute zero
c     fluen    (dp,sc,in)          - fluence at the end of this substep
c     dfluen   (dp,sc,in)          - fluence increment over this substep
c
c     epel     (dp,ar(ncomp),inout)- elastic strain
c     epcrp    (dp,ar(ncomp),inout)- creep strain from previous substep
c     statev   (dp,ar(nstatev),inout)- user state variables from previous 
c                                    (converged) substep. nstatev is the number 
c                                    of state variables set using TB,STATE.
c     var1     (dp,ar(*),--)- not used
c
c
c  output arguments:
c     variable (type,sze,intent)    description
c
c     epel     (dp,ar(ncomp),inout)- elastic strain adjusted for creep increment
c     epcrp    (dp,ar(ncomp),inout)- updated creep strain
c     statev   (dp,ar(nstatev),inout)- updated state variables
c     delcr    (dp,sc,out)         - equivalent creep strain increment (used
c                                    for creep ratio calculation)
c
c  internal variables:
c     variable (type,sze)     description
c     con      (dp,sc)         - temporary variable
c     del      (dp,ar(6))      - creep strain increments
c     epet     (dp,sc)         - equivalent elastic strain (before creep)
c     ept      (dp,ar(6))      - total strain
c     eptot    (dp,sc)         - equivalent total strain, elastic + creep
c     sigen    (dp,sc)         - equivalent stress (before creep)
c     temabs   (dp,sc)         - temperature on the absolute scale
c
 

2.4.8. 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.8.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.

 

2.4.8.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.8.3. Table (TB) Commands 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.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

 

2.4.8.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.8.5. The user_tbelastic API

Following is the interface to the user_tbelastic subroutine:

*deck,user_tbelastic                      USERDISTRIB
      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.8.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 210e3 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,210e3
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.9. Subroutine userfc (Defining Your Own Failure Criteria)

*deck,userfc                      USERDISTRIB
      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.10. Subroutine userCZM (Creating Your Own Cohesive Zone Material)

Use this subroutine to create a user-defined cohesive material (TB,CZM,,,,USER). The subroutine supports interface elements (INTERnnn) only.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

Input is determined by user-specified constants (TBDATA). Up to six constants can be defined per TBDATA command. The number of constants can be any combination of the number of temperatures (NTEMP) and the number of data points per temperature (NPTS), such that NTEMP x NPTS <= 1000.

Example 2.8: Input for a User-Defined Cohesive Material Law

TB,CZM,1,2,4,USER    ! Set material 1 as a user-defined
                                 !    cohesive material option with two temperatures
                                 !    and four data points at each
                                 !    temperature point.
TBTEMP,1.0                       ! First temperature.
TBDATA,1,19e5,0.3,1e3,100,       ! Four cohesive material constants for
                                 !    first temperature.
TBTEMP,2.0                       ! Second temperature.
TBDATA,1,21e5,0.3,2e3,100,       ! Four cohesive material constants for
                                 !    second temperature.

Contact elements do not support a user-defined cohesive material. However, a similar capability can be achieved by defining your own contact interface behavior via the userinter subroutine. For more information, see Defining Your Own Contact Interaction (USERINTER) in the Contact Technology Guide.

Following is the user cohesive material interface:

*deck,userCZM                      USERDISTRIB
      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.10.1. Using State Variables with UserCZM

The UserCZM subroutine for creating user-defined CZM models supports state variables. To use them, initialize the constant table (TB,STATE), then define the initial constants (TBDATA).

By default, the initial values of state variables are set to zero.

Example 2.9: Initializing the Values of State Variables for a User-Defined Cohesive Material Law

TB,STATE,1,,4,            ! Define material 1, which
                          !        has four state variables. 
TBDATA,1,C1,C2,C3,C4,     ! Initialize the four state variables.

 

2.4.11. Subroutine userswstrain (Defining Your Own Swelling Laws)

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

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

Define the material constants (TBDATA). 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.12. Subroutine userthstrain (Defining Your Own Thermal Strain)

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

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

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

2.4.13. Subroutine userfreestrain (Defining Your Own Free-Strain Increment)

You can define the free-strain increment via the TB,CTE,,,,UFSTRAIN command and the userfreestrain subroutine.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

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 Porous Media in the Material Reference.

*deck,userfreestrain                      USERDISTRIB
      subroutine userfreestrain (prop_cte, nusrprop, prop_cte_ufst,
     &                         alp_Biot, porsw, temp, dtemp, nTens,  
     &                         nstatev,ustatev,depfree)               
c
c *** primary function:    return user calculated free strain
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     prop_cte    (dp,ar(*),in) - coefficients of thermal
c                                       expansion defined via TB,CTE
c     nusrprop        (int,sc,in) - number of TB,CTE,,,,UFSTRAIN parameters
c     prop_cte_ufst    (dp,ar(*),in) - material coefficients defined 
c                                         via TB,CTE,,,,UFSTRAIN
c     alp_Biot    (dp,sc,in) - Biot coefficient = 1 - KT /KS
c                              where, KT - tangent bulk modulus
c                                     KS - bulk modulus of skeleton
c     porsw       (dp,sc,in) - porosity
c     temp        (dp,sc,in) - temperature at Gauss point
c     dtemp       (dp,sc,in) - temperature increment at Gauss point
c     nTens      (int,sc,in) - total number of stress components
c     nstatev    (int,sc,in) - number of state variables
c
c  input/output arguments              
c     ustatev   (dp,ar(nstatev),inout) - user state variables

c  output arguments:
c     depfree    (dp,sc,out)      - user free strain increment (volumetric)
c
 

2.4.14. 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                      USERDISTRIB
      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.15. Subroutine UsrShift (Calculating a Pseudotime Time Increment)

This subroutine calculates a pseudotime time increment according to a user-specified shift function (TB,SHIFT,,,,USER). Given the input parameters, the routine must evolve the internal state variables, then return the current and half-step shifted time.

If applicable, specify the number of state variables used (TB,STATE). For more information, see Using State Variables with Material Subroutines in the Material Reference.

*deck,UsrShift                      USERDISTRIB
c Copyright ANSYS.  All Rights Reserved.
      subroutine UsrShift(dxi,dxihalf,timinc,
     &                    temp,dtemp,toffst,propsh,nTerms)
c********************************************************************************
c     calculate pseudotime time increment according
c     to a user specified shift function
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c  input arguments:
c     timinc  (dp,sc,in)         - time increment
c     temp    (dp,sc,in)         - current temperature, t_n+1
c     dtemp   (dp,sc,in)         - temperature increment, t_n+1 - t_n
c     toffst  (dp,sc,in)         - temperature offset to absolute zero
c                                  (specified by TOFFST command)
c     propsh  (dp,ar,in)         - Constants for shift function
c                                  (User's input using TB,SHIFT,,,,USER)
c     nTerms  (int,ar,in)        - number of user defined constants
c                                  (specified in TB,SHIFT,,,nTerms,USER)
c  output arguments:
c    dxi      (dp,sc,out)        - pseudotime increment 
c    dxihalf  (dp,sc,out)        - pseudotime increment over the upper half span
c********************************************************************************
 

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

*deck,userck                      USERDISTRIB
      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.17. Support 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