Writing and Compiling a Custom Material Property in ANSYS Mechanical APDL

Eric Miller
Co-Owner Principal, Simulation and Business Technologies
09/27/2012 PADT, Inc.

DX R13: 02/17/2011 1

Agenda
Note: This presentation is being recorded Introductions Background and Requirements Compiling & Linking The User Material routines Simple Example Thoughts

DX R13: 02/17/2011 2

Introductions

DX R13: 02/17/2011 3

Upcoming Webinars
Upcoming Webinars
October 11, 2012 12:00 - 1:00 MST An Example of Moving Mesh Modeling of a Valve October 25, 2012 12:00 - 1:00 MST Getting Started with ANSYS Engineering Knowledge Manager (EKM) November/December: Start the ANSYS 14.5 Webinars?

See upcoming and past webinars at:

padtincevents.webex.com
Click on ANSYS Webinar Series

DX R13: 02/17/2011 4

About PADT
We Make Innovation Work PADT is an Engineering Services Company
Mechanical Engineering 18 Years of Growth and Happy customers 70ish Employees

3 Business Areas
CAE Sales & Services
Consulting, Training, Sales, Support

Product Development Rapid Prototyping & Manufacturing

Learn More: www.PADTINC.com

We Make Innovation Work
DX R13: 02/17/2011 5

Cube HVPC Systems

Balance between speed and cost
Mini-Cluster 96 Cores / 512 GB RAM / 6 TB Disk Mobile Rack / UPS / Monitor / Keyboard $34,900 Compute Server 32 Cores / 256 GB RAM / 3 TB Disk $14,250 Simulation Workstation (Intel) 12 Cores / 96 GB RAM / 3 TB Disk $11,750 Simulation Workstation (AMD) 12 Cores / 64 GB RAM / 3 TB Disk $6,300

www.CUBE-HVPC.com

DX R13: 02/17/2011 6

PeDAL The APDL Editor

Side-by-side editor and help viewer layout. Instant help on any documented APDL command by pressing F1. Full syntax highlighting for ANSYS v12 Mechanical APDL. Auto-complete drop downs for APDL Commands. APDL Command argument hints while typing commands. Search ANSYS help phrases and keywords. Multiple tabs for the editor and html viewer. Full capability web browser built in allows for rich web experience and web searches.

DX R13: 02/17/2011 7

Connect with PADT

Facebook: facebook.com/padtinc Email Subscriptions:
www.padtinc.com/epubs

Twitter: #padtinc

Web: www.PADTINC.com

LinkedIn: Search on PADT, Inc.

ANSYS User Blog: padtinc.com/focus

DX R13: 02/17/2011 8

Background and Requirements

DX R13: 02/17/2011 9

ANSYS Mechanical APDL = OPEN

MAPDL is the most open FEA commercial program on the planet
Designed and built that way in the 90s

Several ways to access:

APDL Macros command based programming language APDL Math Access to the matrices in MAPDL User routines write and link user routines
Including utilities needed for routines

FORTRAN API
No longer fully documented

You either compile a custom executable or you use external commands

We will do custom executable today External commands link dynamic libraries at run time
Used for user commands and such

DX R13: 02/17/2011 10

User Routines
Can be C or FORTRAN
But we recommend only FORTRAN Provided user subroutines are all FORTRAN

Referred to as User Programmable Features, or UPFs Different types:

Database access User calculated loading Modify or monitor existing ANSYS elements Create a new element Specify your own material behavior Set up ANSYS to run as a subroutine in another program

We are covering materials today, but most is applicable to all the other uses Note: Some routines wont work correctly with Parallel
Verify parallel on test cases.

DX R13: 02/17/2011 11

What you Need to Know

FOTRAN
If you dont know FOTRAN, you can figure it out, but it will be a lot of debugging.
Find a grey haired person to help you.

How the ANSYS solver works

The theory guide is a good place to start For the area you are using, you need to know what equations ANSYS uses and how it applies them. Things like substeps, loadsteps, PREP7 vs POST1 vs SOLU, solver types, etc

The math behind the thing you want to model

Know this math inside and out because you probably will have to morph it to fit within how the solver needs it specified.

DX R13: 02/17/2011 12

What you Need

A full load of ANSYS MAPDL on your machine:
C:\Program Files\ANSYS Inc\v140\ansys\customize\user /ansys_inc/v140/ansys/customize/user/ Should have full include and user directories

Read and Write access to the vNNN directory and all sub folders The Programmers Manual
Mechanical APDL >Programmers Manual

And

DX R13: 02/17/2011 13

The Most Important Thing You Will Learn Today..

DX R13: 02/17/2011 14

YOU MUST USE THE RIGHT COMPILER

The number one problem we see with user routines is people using the wrong compiler!!!!!
It says it everywhere in the help, and still, it is a problem. No maybe, no it kind of works. You must get the right one Visual studio and compilers

// Installation and Licensing Documentation // Windows Installation Guide // 2. Platform Details :: 0

Bottom of the page:
Compiler Requirements for Windows Systems All ANSYS, Inc. products are built and tested using the Visual Studio 2008 SP1 (including the MS C++ compiler) and Intel FORTRAN 11.1 compilers.

// Installation and Licensing Documentation // Linux Installation Guide // 2. Platform Details

Table 2.1

It sometimes says or newer

Nope, you need the one listed

DX R13: 02/17/2011 15

Intel Compiler
ANSYS has been using the Intel compiler for some time Start at the Intel website:
http://software.intel.com/en-us/intel-compilers

You may have to contact them to make sure you get the right version
Be very careful on this, ANSYS usually uses an older version because it is more stable and QAd

DX R13: 02/17/2011 16

But First!
Do you really need a UPF?
Dig a little deeper into the material models and make sure you cant use what is already there

Will your material model work in ANSYS

Does it use the proper formulation and approach Does it fit within the element and solve architecture

DX R13: 02/17/2011 17

Some Advice
Before you get deep into your model get the system working
Compiler, ANSYS, environment variables, etc

Take the standard usermat.f routine and get it to compile and link.
It has the basic TB, BISO model built in as a demo.

Test it
I like to build two beams and run one with a standard BISO and another with the use routine

Get everything working. Then make a small difference to the calculations and make sure you can see it Keep the test routine
If something stops working, you can go back and verify where you are.
DX R13: 02/17/2011 18

Compiling and Linking Your Routine

DX R13: 02/17/2011 19

Windows vs Linux, USERMAT vs Other

You can do all of this on both platforms
We will cover Windows because it is the most common Linux is very similar, just need to do things slightly different in syntax and such

Same goes for other UPFs

Method used for USERMAT works for most other routines

Documentation can be used to see the differences Also: we will talk about USERMAT, it works for creep, hyperelasticity and all other user material UPFs.

DX R13: 02/17/2011 20

Two Ways: Custom Executable and Dynamic

Old Way: Custom Executable
Use a supplied script to compile and link a custom ansys.exe Accessed at run time by command line or launcher options Pros:
Easy to deploy to other machines You know you have a working executable No special setup required, just the options when your run Takes longer to compile, a pain during debug loops Big file to move around

Cons:

Newer Way: Dynamic

Use supplied script or APDL command to link at runtime Can reside anywhere on the solver machine Accessed through environment variable and/or an APDL command Pros:
Quick compile time, great for debugging You can have multiple versions of your routines, pick at run time Using APDL command, you can actually compile at solve time Less control. DLLs all over the place Setup for users can be confusing, Environment variables and paths and such If using compile at run, if the compile fails you dont get real good feedback

Cons:

DX R13: 02/17/2011 21

Using DLLs at Run Time

Decide on a working directory (workdir) and get your usermat.f routine in that directory
Dont change the name!

Copy ansusershared.bat to workdir from:

C:\Program Files\ANSYS Inc\v140\ansys\custom\user\winx64

Open up the FORTRAN command line window CD to workdir Run ansusershared.bat

Enter the name of the routine you want compiled Enter a blank return to get out of the script

To use the DLL you made:

Set the environment variable: ANS_USER_PATH=workdir
DX R13: 02/17/2011 22

Using DLLs at Run Time

Recommended method Use different directories for each version of routines and change environment variable to access what you want Robust, you either have a DLL or you dont

DX R13: 02/17/2011 23

Using /UPF
First, set up some environment variable letting the program know you are going to use /UPF
Make sure that your ANSYS executable directory is in your PATH
It needs to run a script called findUPF.bat

Set ANS_USE_UPF=TRUE

From your working directory, launch the FORTRAN command line Add /upf,usermat.f to your input command file Run ansys in batch mode from the command line shell A DLL will be made, reuse it just like when you make the DLL

DX R13: 02/17/2011 24

Using /UPF
Im not a fan of this method
Have to run ANSYS from the FORTRAN shell
If you set up paths so any routine can compile/link you can run without shell

Need compiler on machine you are solving on If your compile fails you are kind of screwed Added because ABAQUS allows for compile at run

Only works with batch mode

DX R13: 02/17/2011 25

Making a Custom ansys.exe

Open up the FORTAN command line shell You can do this in the custom\user\winx64 directory or in your own directory
I prefer your own. If so, copy: anscust.bat, ansys.lrf, ansysex.def from custom\user\winx64 to your directory

Copy your routine to the workdir CD to the workdir Run anscust.bat

It looks for any UPFs and if it finds them, compiles them You will get an ansys.exe

To use it, specify the path in the launcher (customization/preferences) or with the custom <path> switch
DX R13: 02/17/2011 26

Making a Custom ansys.exe

Takes a while to compile but when it is done, it works. No need for environment variables. Note: Do not rename the executable, must be ansys.exe
Use directories to have different versions

DX R13: 02/17/2011 27

Compiling Recommendations
Debug using the DLL If it is just you, keep using the DLL If you deploy to others, when everything is working, make a new ansys.exe and deploy that Remember to do everything from the FORTRAN shell

DX R13: 02/17/2011 28

The User Material Routines

DX R13: 02/17/2011 29

The Basics
Standard FORTRAN, nothing fancy Well documented Comes with the TB, BISO model Contains several subroutines
Usermat
Doesnt do much, just figures out dimension of element and calls proper routine:

Usermat1d: 1D truss Usermat3d: 3D elements Usermatbm: beam elements Usermatps: plain strain

Works on current element technology only

Does not work with legacy elements

DX R13: 02/17/2011 30

The Basics
The routine gets called for every integration point in your model that is assigned the material number that is defined by a TB, User Stress, Strain, state variables, time increment, strain increment are passed in Your routine updates values and passes them back Read documentation on math
// Programmer's Manual // II. Guide to User-Programmable Features // 2. UPF Subroutines and Functions // 2.4. Subroutines for Customizing Material Behavior

Lots of helper routines provided to make your job easier

General routines you will need Vector utilities Matrix utilities // Programmer's Manual // II. Guide to User-Programmable Features // 4. Subroutines for Users' Convenience

DX R13: 02/17/2011 31

Call
Standard call, all the info that gets passed to the routine is listed

DX R13: 02/17/2011 32

Input Arguments
Documented in the comments

DX R13: 02/17/2011 33

Input/Output
These go in and out, so be careful. Note the VARn is not used right now State variables: Important
These for your use to pass things back and forth How you supply values that you can change
As opposed to properties that dont change Unique to each integration point

Also how you store any specific result or intermediate values at each integration point that you want to plot or list Very powerful See TB info at end of this section

DX R13: 02/17/2011 34

Output
Stuff that is passed out

DX R13: 02/17/2011 35

Important details
Ncomp: Number of terms for each type of element Vector orders Matrix order

DX R13: 02/17/2011 36

Rest of Routine
Declares types Then has and If-then-else to call the proper subroutine for the dimension of the element
Just pass everything through They do this so that the logic of the program is not full of if-then-else statements.

Header info repeats for each subroutine

DX R13: 02/17/2011 37

USERMAT3D
This is where you would do your own thing Simple example for biso is here
Get values Calc elastic and plastic slopes Our first helper function: vmove (copies vectors)

DX R13: 02/17/2011 38

USERMAT3D
This is where you would do your own thing Simple example for biso is here
Get values Calc elastic and plastic slopes Our first helper function: vmove (copies vectors)

DX R13: 02/17/2011 39

USERMAT3D
Calculate the elastic stiffness matrix

DX R13: 02/17/2011 40

Stop
At this point, if the inputs and outputs sound confusing you need to back up and understand ANSYS non-linear solving and how their elements work
Theory manual Hughes, Thomas J.R. and James Winget. Finite Rotation Effects in Numerical Integration of Rate Constitutive Equations Arising in LargeDeformation Analysis. [International Journal for Numerical Methods in Engineering]. 15.9 (1980): 1413-1418.
Book that was used by ANSYS

DX R13: 02/17/2011 41

USERMAT3D
Calculate the stresses Note use of get_ElmData to get elmement call
Documented as part of usermat documentation Used to get info that is not passed in

Get yield

DX R13: 02/17/2011 42

USERMAT3D
Next section checks for yield
If no, use a goto (yes, a goto!) to skip plastic stuff

Do plastic calcs

DX R13: 02/17/2011 43

USERMAT3D
Clean up and get out
Note the 500-600 elastic portion

Thoughts
Simple calcs, yours will probably be much more complex
But steps are the same Gather your properties Branch if needed to for different equations Figure out strain/stress Return the info

Didnt use a lot of calls to other routines Remember it gets called for every integration point
You need to be efficient
DX R13: 02/17/2011 44

USERMAT
Restrictions
Current-technology elements only If you want to plot state variables, you need to use /graph, full Not enough hooks in/out for incompressible materials
Special routine (UserHyper) for that

Only one usermat per model

There is a way around this, use one of your material properties as a flag to access different models Check the flag then call a subroutine for the proper material

DX R13: 02/17/2011 45

TB
TB, User, Mat, NTEMPS, NPTS
Mat is material number NTEMPS is number of temperature points you will provide properties at NPTS, number of property values tb,user,1,2,4 tbtemp,1.0 tbdata,1,19e5, 0.3, 1e3,100 tbtemp,2.0 tbdata,1,21e5, 0.3, 2e3,100

TB, State, Mat,,NPTS

Specifies the material and number of state variables you will use NPTS max is 1000, yes, 1000 Plot/list with ETABLE, ESOL

DX R13: 02/17/2011 46

Simple Example

DX R13: 02/17/2011 47

Modified Slightly from the Help

Two elements, pull on them One is TB,BISO, the other TB,USER Files will be on The Focus Blog tomorrow Modified usermat.f
Scale yield by 0.75

DX R13: 02/17/2011 48

Using the User Mat

Mat2 is the user mat Same properties, just a different table

DX R13: 02/17/2011 49

1: Modify usermat.f
Make sure ANS_USER_PATH is pointing to my user directory Copy to my working directory Edit and in usermat3d subroutine change sigy0 line to:
sigy0 = prop(3)*.75

Save file Launch FORTRAN command line shell ansusershared.bat Run ANSYS with demo input file as input Check output: BISO and USER stresses and strains are different

DX R13: 02/17/2011 50

Results
Note that it tells us we are using a user mat

DX R13: 02/17/2011 51

Lets try it live

DX R13: 02/17/2011 52

Thoughts

DX R13: 02/17/2011 53

Parallel
Things get tricky with parallel You can get it to work Compare parallel and non-parallel on all hardware options
Make sure they match

For shared memory parallel: All UPF s are supported in parallel But dont use Common Block variables.
Each core may have a different value. You dont want to set them different on each core You can usually read them if they are not something that is changed by a solve But dont write to them

DX R13: 02/17/2011 54

Convert UPF into ANSYS

ANSYS does convert customer/university supplied material UPFs into the solver A few things needed:
More than just one user out there wants it, need to show need You have published test results/and or theoretical papers to verify your accuracy The model is free of all legal claims You have time to work with ANSYS development to work out any issues and help with testing

Contact your support provider

If they cant help, contact me.

DX R13: 02/17/2011 55

Hints
Use state variable to set flag for first time used, write something to output that says HEY, Im BEING USED!
Maybe even give more info on the routine Use iout= wrinqr(2) to get output unit

User erhandler() to send out notes, warnings, errors

Could use it rather than write above

User /UNDO to write a *.db file at ansy point Crawl, Walk, Run

DX R13: 02/17/2011 56

Thank You
PADT Enjoys doing these webinars Please consider us as your partner ANSYS Related
Training, Mentoring Consulting Services Customization Sales (if in AZ, NM, CO, UT, NV)

Stratasys 3D Printers and Systems CUBE HVPC Systems Product Development

High-end engineering with practical, real world application

Rapid Prototyping
SLA, SLS, FDM, PolyJet, CNC, Soft Tooling, Injection Molding

Help us by letting us Help you

DX R13: 02/17/2011 57