Lecture 4 Implementing material models: using usermat.f Implementing User-Programmable Features (UPFs) in ANSYS 1
Lecture overview What is usermat.f used for? Stress, strain and material Jacobian matrix How is usermat.f used? usermat.f restrictions Example of application Where to find additional information 2
What is usermat.f used for? The usermat.f subroutine allows writing the stress-strain relationship of a material and applies to any analysis procedure involving mechanical behaviour. The ANSYS installation includes an example which corresponds to a plasticity model, which is the same as TB,BISO, for different stress states and that can be used as reference. Such a routine can be found in the following folder: \ANSYS Inc\v150\ansys\customize\user 3
Stress, strain and material Jacobian matrix The stress measure (σ) used by the subroutine is the Cauchy stress (true stress), and the strain measure (ε) is the logarithmic strain (true strain). The strains and incremental strains passed into usermat.f are the total mechanical strains from which the thermal strains (if they exist) are subtracted. usermat.f must also provide the material Jacobian matrix defined as: Jacobian = σ ε ij ij being σ ε ij ij the stress increment the strain increment 4
Stress, strain and material Jacobian matrix One important remark to mention is that ANSYS outputs engineering shear strains whether NLGEOM is ON or OFF. This is true for usermat.f as well. Engineering shear strains are twice the tensor shear strains. 5
Stress, strain and material Jacobian matrix usermat.f 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.f for the rigid body rotation, there is no need to apply additional rotation within usermat.f. 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. 6
Stress, strain and material Jacobian matrix usermat.f assumes use of a nonlinear constitutive model, so results are copied from integration points to nodes. In MAPDL, for linear elastic materials (or if stress value < yield stress value), the default is to extrapolate stresses and strains from integration points to nodes. Consequently, when comparing results for usermat.f with linear elastic materials, differences may be seen. Therefore, to make the comparison valid, one should use the APDL command ERESX,NO to force copying stresses and strains at integration points to nodes, even for linear elastic materials. There is no way, currently, to have usermat.f extrapolate stresses and strains from integration points to nodes (they are always copied). However, it is possible to do so in UserElem.F (explained in Lecture 7). 7
Stress, strain and material Jacobian matrix Stress, strain, and the material Jacobian tensors are stored in a vector or matrix format. In particular, the order of components for all tensors is as follows: 8
Stress, strain and material Jacobian matrix The order of components for the material Jacobian matrix is as follows: 9
How is usermat.f used? The file usermat.f consists of 4 routines which are called depending on the corresponding stress state. Below is a list of such 4 routines with a brief description of the stress/strain state as well as finite elements they can be used in conjunction with: usermat3d usermatps usermatbm usermat1d 3D solid elements or plane elements in plane strain or axisymmetric stress state plane stress states (such as PLANE182, PLANE183 or SHELL181) 3D beam elements (BEAM188, BEAM189) 1D truss elements (LINK180) 10
How is usermat.f used? Main input arguments are listed below: Number of state variables to be defined with TB,STATE command Number of material properties to be defined with TB,USER command T T t ε t ε Vector of material properties F F t t + t 11
How is usermat.f used? Main input/output arguments are listed below: Stress at time to be updated at time t t + t State variables at time to be updated at time t t + t 12
How is usermat.f used? Main output arguments are listed below: Bisection occurs if user routine does not converge material Jacobian matrix 13
usermat.f restrictions The following restrictions apply to the usermat.f subroutine: The subroutine supports current-technology elements only and is not applicable to legacy elements. Details on current-technology elements can be found here: ANSYS Documentation > Mechanical APDL > Element Reference > 2. Element Classifications > 2.4. Current-Technology Elements The subroutine usermat.f is not applicable to legacy elements for which dedicated subroutines should be used instead. Further information is available in the online documentation: ANSYS Documentation > Mechanical APDL > Feature Archive > IV. Legacy Elements 14
usermat.f restrictions State variables (defined via the TB,STATE command) are supported only by full graphics in the POST1 postprocessor; The subroutine is not intended for modelling incompressible elastic materials (*), such as hyperelastic materials. A special treatment such as a penalty approach may be needed to ensure incompressibility. In any case, if the material exhibits nearly incompressible behavior, use a finite tangent bulk modulus. (*) Fully-incompressible materials can be modeled using the subroutine UserHyper.F, which will be described in Lecture 5. 15
Example of application A simple bilinear plasticity material model, identical to TB,BISO, is used to demonstrate the user material subroutine usermat.f. The example is a two-element test case under simple tension. Element 1 has material defined using the TB,BISO option, while Element 2 has material defined using the TB,USER option. A 100% deformation is applied to both elements. Finite deformation (NLGEOM,ON) is considered. The /POST26 processor results of stress components and plastic strain components are printed for both elements and are expected to be the same. 16
Example of application Below is the description of the APDL syntax needed to use usermat.f. In this specific example the user material was assigned to material #2 and its mechanical properties, namely Young s modulus, Poisson s ratio, yielding stress and tangent modulus, are temperature-dependent. The number of state variables is 8. TB,USER,2,2,4 TBTEMP,1.0 TBDATA,1,190000,0.3,100,10 TBTEMP,2.0 TBDATA,1,210000,0.3,200,10 TB,STATE,2,,8 17
Example of application Output information: TB,BISO vs. TB,USER Information regarding the number of state variables, inputted using the TB,STATE syntax, is provided as well: 18
Example of application /POST26 output: results are identical 19
Example of application In order to be able to get the values of the state variables, the following APDL command should be inserted at the /SOLU processor level: OUTRES,SVAR,ALL In particular, the option ALL allows writing the results for every substep. Also, it might be convenient to print the values of the state variables (8 in this example) in the output file. This can be achieved by means of the following do-loop to be inserted at the /POST1 processor level: *DO,AR99,1,8 PRESOL,SVAR,AR99 *ENDDO 20
Example of application Below is the list of the state variables utilized in this example: SVAR 1 ----- > SVAR 2 ----- > SVAR 3 ----- > SVAR 4 ----- > SVAR 5 ----- > SVAR 6 ----- > SVAR 7 ----- > SVAR 8 ----- > Equivalent plastic strain X component of plastic strain Y component of plastic strain Z component of plastic strain XY component of plastic strain YZ component of plastic strain XZ component of plastic strain von Mises stress as also specified in the subroutine usermat3d: 21
Example of application /POST1 output: printout of state variable #1 (equivalent plastic strain) at last substep. 22
Example of application State variables can also be plotted (the first one in this example). This can be done by means of the following APDL command: PLESOL,SVAR,1 However, it is worth mentioning that this is not supported by PowerGraphics. Therefore there is the need to insert the /GRAPH,FULL command in the script. We can also print/plot the evolution of the state variables by utilizing this undocumented APDL command: ESOL,,,,SVAR,1 PRVAR,1 (or PLVAR,1 to plot) 23
Example of application /POST26 output: graph of the evolution of state variable #1 (equivalent plastic strain). 0.692053 24
Example of application /POST26 output: printout of the evolution of state variable #1 (equivalent plastic strain). 25
Example of application /POST1 output: contour plot of the equivalent plastic strain at last substep. We notice that the results are identical for both models. APDL commands: /POST1 PLESOL,NL,EPEQ,0,1.0 (A) structure with TB,BISO material model (A) (B) (B) structure with user-defined elasto-plastic material model 26
Example of application /POST1 output: contour plot of state variable #1 (equivalent plastic strain) at last substep. We notice that it is non-zero only when considering the structure (cube on the right) with the user-defined routine. APDL commands: /POST1 PLESOL,SVAR,1 (A) structure with TB,BISO material model (A) (B) (B) structure with user-defined elasto-plastic material model 27
Where to find additional information Additional information on rate-independent plasticity can be found in the online manual: ANSYS Documentation > Mechanical APDL > Material Reference > 3. Material Models // 3.4. Rate-Independent Plasticity ANSYS Documentation > Mechanical APDL > Theory Reference > 4. Structures with Material Nonlinearities > 4.2. Rate-Independent Plasticity ANSYS Documentation > Mechanical APDL > Structural Analysis Guide > 8. Nonlinear Structural Analysis > 8.4. Modeling Material Nonlinearities Also, the ANSYS training course ANSYS Mechanical Advanced Nonlinear Materials provides detailed information regarding plasticity and, in this respect, it is recommended. 28
Where to find additional information Another usage example of the usermat subroutine is available in the online documentation, precisely in Chapter 40 of the Technology Demonstration Guide: ANSYS Documentation > Mechanical APDL > Technology Demonstration Guide > 40. Large-Deformation Neo-Hookean Analysis (via UserMat Subroutine) The problem formulates a 3-D large deformation, hyperelastic material to demonstrate the user material capability in nonlinear geometry analyses. Details are given for stress and material tangent calculations and formulation in a co-rotated frame, as well as conversion of tensor quantities to Voigt notation. 29