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.
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.
The following UserMat topics are available:
For a UserMat subroutine example, see Appendix C: User Material (UserMat) Subroutine Example.
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.
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:
11, 22, 33, 12, 23, 13
11, 22, 33, 12
11, 22, 12
11, 13, 12
11
The order of components for the material Jacobian matrix is as follows:
| 1111 | 1122 | 1133 | 1112 | 1123 | 1113 |
| 2211 | 2222 | 2233 | 2212 | 2223 | 2213 |
| 3311 | 3322 | 3333 | 3312 | 3323 | 3313 |
| 1211 | 1222 | 1233 | 1212 | 1223 | 1213 |
| 2311 | 2322 | 2333 | 2312 | 2323 | 2313 |
| 1311 | 1322 | 1333 | 1312 | 1323 | 1313 |
| 1111 | 1122 | 1133 | 1112 |
| 2211 | 2222 | 2233 | 2212 |
| 3311 | 3322 | 3333 | 3312 |
| 1211 | 1222 | 1233 | 1212 |
| 1111 | 1122 | 1112 |
| 2211 | 2222 | 2212 |
| 1211 | 1222 | 1212 |
| 1111 | 1113 | 1112 |
| 1311 | 1313 | 1312 |
| 1211 | 1213 | 1212 |
| 1111 |
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*************************************************************************
The UserMat subroutine uses the following Input, Input/Output, and Output variables. Do not change them
in the subroutine code.
UserMat Input Arguments
| |
| matId | Integer variable containing the material ID number. |
| elemId | Integer variable containing the element number. |
| kDomIntPt | Integer variable containing the material integration point number. |
| kLayer | Integer variable containing the layer number. |
| kSectPt | Integer variable containing section point number. |
| ldstep | Integer variable containing load step number. |
| isubst | Integer variable containing substep number. |
| nDirect | Number of direct components of the stress or strain vector at material point. |
| nShear | Number of shear components of the stress or strain vector at material point (engineering components). |
| ncomp | Total number of the stress or strain components at material point (nDirect + nShear). |
| nstatev | Number of state variables, specified by the
NPTS value in the
TB,STATE command. |
| nProp | Number of material constants, specified by the
NPTS value in the
TB,USER command. |
| Temp | Double-precision variable containing the current temperature. |
| dTemp | Double-precision variable containing the current temperature increment. |
| Time | Double-precision variable containing the total time at the beginning of the time increment. |
| dTime | Double-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
For large-deformation problems,
(NLGEOM,ON), the strain components are
updated to account for rigid body rotation before they are
passed to When the mixed u-P formulation option
( |
| 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
( |
| prop | Double-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. |
| coords | Double-precision array containing the current coordinates of the material integration points. Array size is 3. |
| defGrad_t | Double-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). |
| defGrad | Double-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
When the mixed u-P formulation option
( |
| 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. |
| epseq | Equivalent 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. |
| sedEl | Elastic work. It is used for output purposes only and does not affect the solution. |
| sedPl | Plastic 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:
Set keycut = 1 when | ||
| epsZZ | Strain 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:
| ||
| dsdePl(ncomp,ncomp) |
Double-precision array containing the material Jacobian
matrix 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
( | ||
| 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. | ||
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.
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.
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.
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.
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).
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
| |
| inquire | String variable containing a query argument. |
| elemId | Integer variable containing the element number. |
| kDomIntPt | Integer variable containing the material integration point number. |
| nvect | Integer variable containing number of variable to be retrieved. |
| Vect(*) | Variable array containing the retrieved variables. |
Valid inquire
Argument Variables
| |
| ESYS | Element coordinate system (ESYS). |
| ISIG | Initial stress. |
| TREF | Reference temperature. |
The following functions are available for use with
UserMat. ANSYS, Inc. provides them for your
convenience.
Utility Functions for
UserMat
| |
|
vzero(
|
Initializes array
The value |
|
vmult(
|
Multiplies vector
The value |
|
vmult1(
|
Multiplies vector
The value |
|
maxb(
|
Multiplies two double-precision matrices and outputs the
result as
The value The The value |
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:
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.
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*************************************************************************
The UserMatTh subroutine uses the following Input, Input/Output, and Output variables. Do not change them
in the subroutine code.
UserMatTh Input Arguments
| |
| matId | Integer variable containing the material ID number. |
| elemId | Integer variable containing the element number. |
| kDomIntPt | Integer variable containing the material integration point number. |
| kLayer | Integer variable containing the layer number. |
| kSectPt | Integer variable containing section point number. |
| ldstep | Integer variable containing load step number. |
| isubst | Integer variable containing substep number. |
| ncomp | Integer variable containing spatial dimension number: 1 for 1-D, 2 for 2-D, or 3 for 3-D. |
| nStatev | Number of state variables, specified via the
NPTS value in the
TB,STATE command. |
| nProp | Number of material constants, specified via the
NPTS value in the
TB,USER command. |
| Temp | Double-precision variable containing the current temperature. |
| dTemp | Double-precision variable containing the current temperature increment. |
| Time | Double-precision variable containing the total time at the beginning of the time increment. |
| dTime | Double-precision variable containing the current time increment. |
| prop | Double-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. |
| coords | Double-precision array containing the current coordinates of the material integration points. Array size is 3. |
| tgrad | Double-precision array of size ncomp containing temperature gradient at the beginning of the time increment. |
UserMatTh Input/Output
Arguments
| |
| hgen | Double-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. |
| dens | Double 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:
Set keycut = 1 when | ||
| cutFactor | Double-precision variable containing the user-defined time-step size-control factor. | ||
| dudt | Double-precision variable containing the unit mass internal energy variation with respect to temperature. | ||
| dudg | Double-precision array of size (ncomp,ncomp) containing the unit mass internal thermal energy variation with respect to the spatial gradients of temperature. | ||
| flux | Double-precision array of size ncomp containing the heat flux vector. | ||
| dfdt | Double-precision array of size ncomp containing the heat flux vector variation with respect to temperature. | ||
| dfdg | Double-precision array of size (ncomp,ncomp) containing the heat flux vector variation with respect to the spatial gradients of temperature. | ||
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.
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.
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.
The following functions are available for use with
UserMatTh. ANSYS, Inc. provides them for your
convenience.
Utility Functions for
UserMatTh
| |
|
vzero(
|
Initializes array
The value |
|
vmult(
|
Multiplies vector
The value |
|
vmult1(
|
Multiplies vector
The value |
|
maxb(
|
Multiplies two double-precision matrices and outputs the
result as
The value The The value |
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
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
Subroutine user_tbelastic provides an interface for
defining your own material linear elastic properties
(TB,ELASTIC). The following topics are available:
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.
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.
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.
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
| I | Element number | |||
matId
| I | Material number | |||
coords
| I | Coordinates of material integration point at initial configuration (geometry) | |||
temp
| I | Current temperature at material integration point | |||
nprop
| I / O |
Number of constants to be returned (input) or actually returned (output), as follows:
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
| O | The material elastic constants to be defined |
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
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
*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
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
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
*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
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
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*************************************************************************
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