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
