ANSYS_Mechanical_APDL_Programmers_Reference

【实例截图】

【核心代码】

Table of Contents
Preface ...................................................................................................................................................... xix
1. Guide to Interfacing with ANSYS ............................................................................................................ 1
1. Format of Binary Data Files ............................................................................................................... 3
1.1. Understanding Mechanical APDL Binary Files .............................................................................. 3
1.1.1. Conventions Used to Describe Binary Files .......................................................................... 4
1.1.2.The Standard Header for Mechanical APDL Binary Files ....................................................... 4
1.2. Description of the Results File ..................................................................................................... 5
1.2.1. Nomenclature .................................................................................................................... 6
1.2.2. Standard ANSYS File Header ............................................................................................... 6
1.2.3. Results File Format ............................................................................................................. 6
1.3. Description of the Reduced Displacement File ........................................................................... 28
1.3.1. Standard Mechanical APDL File Header ............................................................................. 28
1.3.2. RDSP File Format .............................................................................................................. 28
1.4. Description of the Reduced Complex Displacement File ............................................................. 32
1.4.1. Standard Mechanical APDL File Header ............................................................................. 32
1.4.2. RFRQ File Format .............................................................................................................. 32
1.5. Description of the Modal Results File ......................................................................................... 35
1.5.1. Standard Mechanical APDL File Header ............................................................................. 35
1.5.2. MODE File Format ............................................................................................................ 35
1.6. Description of the Element Matrices File .................................................................................... 40
1.6.1. Standard Mechanical APDL File Header ............................................................................. 40
1.6.2. EMAT File Format .............................................................................................................. 40
1.7. Description of the Substructure Matrices File ............................................................................. 45
1.7.1. Standard Mechanical APDL File Header ............................................................................. 45
1.7.2. SUB File Format ................................................................................................................ 45
1.8. Description of the Component Mode Synthesis Matrices (CMS) File ............................................ 50
1.8.1. Standard Mechanical APDL File Header ............................................................................. 50
1.8.2. CMS File Format ............................................................................................................... 51
1.8.3.TCMS File Format .............................................................................................................. 53
1.9. Description of the Full Stiffness-Mass File .................................................................................. 54
1.9.1. Standard Mechanical APDL File Header ............................................................................. 54
1.9.2. FULL File Format .............................................................................................................. 55
1.10. Description of the Substructure Displacement File ................................................................... 63
1.10.1. Standard Mechanical APDL File Header ........................................................................... 63
1.10.2. DSUB File Format ............................................................................................................ 63
2. Accessing Binary Data Files ............................................................................................................. 67
2.1. Accessing Mechanical APDL Binary Files .................................................................................... 67
2.1.1. Access Routines for Results Files ....................................................................................... 67
2.1.2. Characteristics of Mechanical APDL Binary Files ................................................................ 68
2.1.3.Viewing Binary File Contents ............................................................................................ 69
2.1.4. Abbreviations .................................................................................................................. 69
2.1.5. binini (Initializing Buffered Binary I/O Systems) ................................................................. 69
2.1.6. Function sysiqr (Retrieving the Status of a File) .................................................................. 70
2.1.7. Function biniqr8 (Retrieving System-Dependent Parameters) ............................................ 70
2.1.8. Function binset (Opening a Blocked Binary File or Initializing Paging Space) ...................... 71
2.1.9. Subroutine bintfo (Defining Data for a Standard Mechanical APDL File Header) ................. 72
2.1.10. Subroutine binhed8 (Writing the Standard Mechanical APDL File Header) ....................... 72
2.1.11. Subroutine binrd8 (Reading Data from a Buffered File) .................................................... 73
2.1.12. Subroutine binwrt8 (Writing Data to a Buffered File) ....................................................... 74
iii
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
2.1.13. Subroutine exinc4 (Decoding an Integer String into a Character String) ........................... 75
2.1.14. Subroutine inexc4 (Coding a Character String into an Integer String) ............................... 75
2.1.15. Subroutine binclo (Closing or Deleting a Blocked Binary File) .......................................... 76
2.1.16. Subroutine largeIntGet (Converting Two Integers into a Pointer) ..................................... 76
2.2. Demonstration Routines ........................................................................................................... 76
2.2.1. Program bintst (Demonstrates Dumping a Binary File and Copying It for Comparison Pur-
poses) ...................................................................................................................................... 77
2.2.1.1. Common Variables: ................................................................................................. 77
2.2.2. Subroutine bintrd (Demonstrates Printing a Dump of File Contents) .................................. 77
2.2.3. Subroutine bintwr (Demonstrates Copying Binary File Contents) ....................................... 78
2.2.4. Program ResRdDemo (Demonstrates Reading a Results File) ............................................. 78
2.2.5. Program ResWrDemo (Demonstrates Writing a Results File) ............................................... 79
2.3. Retrieving Data from the Results File ......................................................................................... 79
2.3.1. Results File Reader ........................................................................................................... 79
2.3.1.1. Compile and Link with the Result File Reader Code ................................................... 80
2.3.1.2. Open an Existing Results File .................................................................................... 81
2.3.1.3. Basic Concepts ........................................................................................................ 81
2.3.1.3.1.Vector Format Description ............................................................................... 81
2.3.1.3.2. Get a Record in the Results File ........................................................................ 81
2.3.1.3.3. Repeatedly Reading Records of the Results File ................................................ 82
2.3.1.4. Extract Nodes and Elements .................................................................................... 83
2.3.1.4.1. Extract the Nodes ........................................................................................... 83
2.3.1.4.2. Extract the Elements ....................................................................................... 83
2.3.1.5. Extract a Solution Vector .......................................................................................... 84
2.3.1.6. Example: Extract a Nodal Solution Vector .................................................................. 85
2.3.1.7. Example: Extract an Element Solution Vector ............................................................ 85
2.3.1.8. Example: Using the Results File Reader in a Standalone Program ............................... 86
2.3.2. Results File Access Routines .............................................................................................. 88
2.3.2.1. Overview of the Routines ......................................................................................... 88
2.3.2.2. ResRdBegin (Opening the File and Retrieving Global Information) ............................ 89
2.3.2.3. ResRdGeomBegin (Retrieving Global Geometry Information) ................................... 90
2.3.2.4. ResRdType (Retrieving Element Types) ..................................................................... 90
2.3.2.5. ResRdReal (Retrieving Real Constants) ...................................................................... 91
2.3.2.6. ResRdCsys (Retrieving Coordinate Systems) ............................................................. 91
2.3.2.7. ResRdNode (Retrieving Nodal Coordinates) .............................................................. 91
2.3.2.8. ResRdElem (Retrieving Elements) ............................................................................. 92
2.3.2.9. ResRdSectMatBegin (Retrieving Global Section and Material Information) ................ 92
2.3.2.10. ResRdSect (Retrieving Section Data) ....................................................................... 92
2.3.2.11. ResRdMat (Retrieving Material Data) ...................................................................... 93
2.3.2.12. ResRdSolBegin (Retrieving Result Set Location) ...................................................... 93
2.3.2.13. ResRdDisp (Retrieving Nodal Solution) ................................................................... 93
2.3.2.14. ResRdRfor (Retrieving Reaction Solution) ............................................................... 94
2.3.2.15. ResRdFix (Retrieving Applied Nodal Constraints) .................................................... 94
2.3.2.16. ResRdForc (Retrieving Applied Nodal Loads Solution) ............................................. 94
2.3.2.17. ResRdEstr (Retrieving Element Solutions) ............................................................... 95
3.The CDWRITE (CDB) File Format ...................................................................................................... 97
3.1. Using the CDWRITE Command .................................................................................................. 97
3.1.1. Customizing Degree of Freedom Labels: the /DFLAB Command ........................................ 97
3.2. Coded Database File Commands ............................................................................................... 99
3.2.1. BFBLOCK Command ......................................................................................................... 99
3.2.2. BFEBLOCK Command ..................................................................................................... 100
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iv
Programmer's Reference
3.2.3. CE Command ................................................................................................................. 101
3.2.4. CP Command ................................................................................................................. 102
3.2.5. CMBLOCK Command ...................................................................................................... 102
3.2.6. CYCLIC Command .......................................................................................................... 103
3.2.7. EBLOCK Command ......................................................................................................... 109
3.2.8. EN Command ................................................................................................................. 110
3.2.9. LOCAL Command ........................................................................................................... 110
3.2.10. M Command ................................................................................................................ 111
3.2.11. MPDATA Command ...................................................................................................... 111
3.2.12. MPTEMP Command ...................................................................................................... 112
3.2.13. N Command ................................................................................................................. 112
3.2.14. NBLOCK Command ....................................................................................................... 112
3.2.15. *PREAD Command ....................................................................................................... 113
3.2.16. R Command ................................................................................................................. 114
3.2.17. RLBLOCK Command ..................................................................................................... 114
3.2.18. SE Command ................................................................................................................ 115
3.2.19. SECBLOCK Command ................................................................................................... 115
3.2.20. SFBEAM Command ....................................................................................................... 116
3.2.21. SFE Command .............................................................................................................. 117
2. Guide to User-Programmable Features .............................................................................................. 119
1. Understanding User Programmable Features (UPFs) ................................................................... 121
1.1.What Are User Programmable Features? .................................................................................. 122
1.2.What You Should Know Before Using UPFs ............................................................................... 122
1.3. Planning Your UPFs ................................................................................................................. 124
1.4. Studying the Mechanical APDL User Routines .......................................................................... 124
1.5. Programming in Languages Other Than FORTRAN ................................................................... 124
1.6. Developing UPFs: a Suggested Strategy ................................................................................... 125
1.7. Include Decks ......................................................................................................................... 125
1.8. Choosing a Linking Method .................................................................................................... 127
1.9. Compiling and Linking UPFs on Linux Systems ........................................................................ 127
1.9.1. Using the /UPF Command .............................................................................................. 128
1.9.2. Creating a Shared Library ............................................................................................... 129
1.9.3. Using the ANS_ADMIN Utility ......................................................................................... 129
1.9.4. Downloading and Installing the GCC Compiler ................................................................ 130
1.10. Sharing Data Between User Routines ..................................................................................... 130
1.11. Compiling and Linking UPFs on Windows Systems ................................................................. 132
1.11.1. Using the /UPF Command ............................................................................................ 133
1.11.1.1. Using the /UPF Command on a Windows HPC Server System ................................ 135
1.11.2. Creating a Dynamic-link (DLL) Library ........................................................................... 136
1.11.3. Using the ANS_ADMIN Utility ....................................................................................... 137
1.12. Activating UPFs ..................................................................................................................... 139
1.13. Running Your Custom Executable .......................................................................................... 140
1.14.Verifying Your Routines ......................................................................................................... 141
1.15. Debugging Commands ......................................................................................................... 141
1.16. Other Useful Commands ....................................................................................................... 141
1.17. Generating Output ................................................................................................................ 142
1.18. Reading Large Data Files More Rapidly .................................................................................. 142
2. UPF Subroutines and Functions .................................................................................................... 143
2.1. Creating a New Element .......................................................................................................... 143
2.1.1. Input and Output Abbreviations ..................................................................................... 145
2.1.2. Creating a New Element via the User-Defined Element API .............................................. 145
v
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Programmer's Reference
2.1.2.1. Subroutine UserElem (Writing Your Own Elements) ................................................ 147
2.1.2.2. Subroutine ElemGetMat (Calling the Standard Structural Material Library) .............. 159
2.1.3. Creating a New Element by Directly Accessing the Program Database ............................. 163
2.1.3.1. User Subroutines ................................................................................................... 163
2.1.3.2. Subroutine uec100 (Defining Characteristics of the usr100 Subroutine) .................. 164
2.1.3.2.1. Subroutines uec101 through uec105 ............................................................. 164
2.1.3.3. Subroutine uex100 (Overriding Element Characteristic Defaults) ............................ 164
2.1.3.3.1. Subroutines uex101 through uex105 ............................................................. 165
2.1.3.4. Subroutine uel100 (Calculating Element Matrices, Load Vectors, and Results) ........... 165
2.1.3.4.1. Subroutines uel101 through uel105 .............................................................. 166
2.1.3.5. Subroutine uep100 (Printing Output for User Elements in POST1 via
PRESOL,ELEM) ................................................................................................................. 166
2.1.3.5.1. Subroutines uep101 through uep105 ............................................................ 167
2.1.3.6. Subroutine usertr (Adjusting the Nodal Orientation Matrix) .................................... 167
2.1.3.7. Subroutine userac (Accessing Element Information) ............................................... 167
2.2. Supporting Subroutines for Element Creation .......................................................................... 168
2.2.1. Subroutine nminfo (Returning Element Reference Names) .............................................. 168
2.2.2. Subroutine svgidx (Fetching the Index for Saved Variables) ............................................. 169
2.2.3. Subroutine svrget (Fetching Saved Variable Data for an Element) ..................................... 169
2.2.4. Subroutine svrput (Writing an Element's Saved Variable Set) ........................................... 170
2.2.5. Subroutine svpidx (Writing the Saved Variable Element Index to a File) ............................ 170
2.2.6. Subroutine mreuse (Determining Which Element Matrices Can Be Reused) ...................... 171
2.2.7. Subroutine subrd (Reading Element Load Data for a Substructure Generation Run) ......... 172
2.2.8. Subroutine subwrt (Writing an Element Load Vector to a File for a Substructure Generation
Run) ....................................................................................................................................... 173
2.2.9. Subroutine rvrget (Fetching Real Constants for an Element) ............................................ 173
2.2.10. Subroutine propev (Evaluating a Group of Material Properties) ...................................... 174
2.2.11. Subroutine prope1 (Evaluating One Material Property) .................................................. 174
2.2.12. Subroutine pstev1 (Evaluating Material Properties for 1-D Elements) ............................. 175
2.2.13. Subroutine tbuser (Retrieving User Table Data) .............................................................. 175
2.2.14. Subroutine plast1 (Updating an Element's Plastic History) ............................................. 176
2.2.15. Subroutine plast3 (Updating an Element's Plastic History, 4 or 6 components) ................ 176
2.2.16. Subroutine creep1 (Updating an Element's Creep History) ............................................. 177
2.2.17. Subroutine creep3 (Updating an Element's Creep History, 3-D Elements) ....................... 178
2.2.18. Subroutine swell1 (Updating an Element's Swelling History) .......................................... 178
2.2.19. Subroutine swell3 (Updating an Element's Swelling History, 3-D Elements) .................... 179
2.2.20. Function elLenPsvrBuf (Determining Additional ESAV Record for Plasticity) .................... 180
2.2.21. Function nlget (Retrieving Material Nonlinear Property Information) ............................. 180
2.2.22. Subroutine usereo (Storing Data in the nmisc Record) ................................................... 181
2.2.23. Subroutine eldwrtL (Writing Element Data to a File) ...................................................... 181
2.2.24. Subroutine eldwrnL (Writing Element Nonsummable Miscellaneous Data to the Results
File) ........................................................................................................................................ 182
2.2.25. Subroutine trrot (Calculating the Rotation Vector) ......................................................... 182
2.2.26. Subroutine rottr (Calculating the Transformation Matrix) ............................................... 182
2.2.27. Subroutine xyzup3 (Updating an Element's 3-D Nodal Coordinates) .............................. 183
2.2.28. Subroutine tmpget (Defining Current Temperature Loads) ............................................ 183
2.2.29. Subroutine prsget (Defining Current Pressure Loads) ..................................................... 184
2.2.30. Subroutine cnvget (Defining Current Convection Loads) ............................................... 184
2.2.31. Subroutine hgnget (Defining Current Heat Generation Loads) ....................................... 185
2.2.32. Subroutine prinst (Calculating Principal Stress and Stress Intensity) ............................... 185
2.3. Subroutines for Modifying and Monitoring Existing Elements .................................................. 186
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. vi
Programmer's Reference
2.3.1. Subroutine userou (Storing User-Provided Element Output) ............................................ 186
2.3.2. Subroutine useran (Modifying Orientation of Material Properties) ................................... 187
2.3.3. Subroutine userrc (Performing User Operations on COMBIN37 Parameters) ..................... 188
2.3.4. Subroutine UElMatx (Accessing Element Matrices and Load Vectors) ............................... 188
2.3.5. Subroutine uthick (Getting User-Defined Initial Thickness) .............................................. 189
2.3.6. Subroutine UsrFictive (Providing User-Defined Fictive Temperature Relationship) ............ 189
2.3.7. Subroutine uflex (Calculating Flexibility Factors for PIPE288 and PIPE289) ........................ 190
2.3.8. Subroutine UsrShift (Calculating Pseudotime Time Increment) ........................................ 190
2.3.9. Subroutine UTimeInc (Overriding the Program-Determined Time Step) ........................... 191
2.3.10. Subroutine UCnvrg (Overriding the Program-Determined Convergence) ....................... 191
2.4. Subroutines for Customizing Material Behavior ........................................................................ 192
2.4.1. Subroutine UserMat (Creating Your Own Material Model) ................................................ 193
2.4.1.1. UserMat Element Support ...................................................................................... 193
2.4.1.2. UserMat Overview ................................................................................................. 193
2.4.1.2.1.Time Domain ................................................................................................ 194
2.4.1.2.2. Harmonic ...................................................................................................... 194
2.4.1.3. Stress, Strain, and Material Jacobian Matrix ............................................................. 195
2.4.1.4.The UserMat API .................................................................................................... 196
2.4.1.5. UserMat Variables ................................................................................................. 198
2.4.1.6.Table (TB) Commands for UserMat ......................................................................... 202
2.4.1.7. Material Constitutive Integration with UserMat ....................................................... 203
2.4.1.8. UserMat Restrictions .............................................................................................. 203
2.4.1.9. Accessing Material and Element Data for UserMat .................................................. 204
2.4.1.10. Utility Functions for UserMat ................................................................................ 205
2.4.2. Subroutine UserMatTh (Creating Your Own Thermal Material Model) ............................... 205
2.4.2.1. UserMatTh Element Support .................................................................................. 206
2.4.2.2.The UserMatTh API ................................................................................................ 206
2.4.2.3. UserMatTh Variables ............................................................................................. 207
2.4.2.4.Table (TB) Commands for UserMatTh ..................................................................... 209
2.4.2.5. UserMatTh Restrictions .......................................................................................... 210
2.4.2.6. Utility Functions for UserMatTh .............................................................................. 210
2.4.3. Subroutine UserHyper (Writing Your Own Isotropic Hyperelasticity Laws) ........................ 211
2.4.4. Subroutine UserHyperAniso (Writing Your Own Anisotropic Hyperelasticity Laws) ........... 212
2.4.4.1. Input Parameters ................................................................................................... 212
2.4.4.2. Invariants and Potential Derivatives ........................................................................ 213
2.4.4.3. UserHyperAniso API ............................................................................................... 214
2.4.5. Subroutine UserCreep (Defining Creep Material Behavior) ............................................... 215
2.4.6. Subroutine user_tbelastic (Defining Material Linear Elastic Properties) ............................ 216
2.4.6.1. Overview of the user_tbelastic Subroutine ............................................................. 217
2.4.6.2. Data Types Supported by user_tbelastic ................................................................. 217
2.4.6.3.Table (TB) Command for user_tbelastic .................................................................. 217
2.4.6.4. User Interface for user_tbelastic ............................................................................. 217
2.4.6.5.The user_tbelastic API ............................................................................................ 218
2.4.6.6. Usage Example for user_tbelastic ........................................................................... 219
2.4.7. Subroutine userfc (Defining Your Own Failure Criteria) .................................................... 220
2.4.8. Subroutine userCZM (Defining Your Own Cohesive Zone Material) .................................. 221
2.4.9. Subroutine userswstrain (Defining Your Own Swelling Laws) ........................................... 222
2.4.10. Subroutine userck (Checking User-Defined Material Data) ............................................. 223
2.4.11. Supporting Function egen ............................................................................................ 223
2.4.12. Subroutine userfld (Update User-Defined Field Variables) .............................................. 224
2.4.13. Subroutine userthstrain (Defining Your Own Thermal Strain) ......................................... 225
vii
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Programmer's Reference
2.5. Subroutines for Customizing Contact Interfacial Behavior ........................................................ 225
2.5.1. Subroutine usercnprop (Programming Your Own Contact Properties) .............................. 226
2.5.2. Subroutine userfric (Writing Your Own Friction Laws) ...................................................... 230
2.5.3. Subroutine userinter (Writing Your Own Contact Interactions) ......................................... 232
2.5.4. Subroutine userwear (Writing Your Own Wear Law) ......................................................... 238
2.6. Subroutines for Customizing Loads ......................................................................................... 240
2.6.1. Subroutine usrefl (Changing Scalar Fields to User-Defined Values) ................................... 240
2.6.2. Subroutine userpr (Changing Element Pressure Information) ........................................... 241
2.6.3. Subroutine usercv (Changing Element Face Convection Surface Information) .................. 242
2.6.4. Subroutine userfx (Changing Element Face Heat Flux Surface Information) ...................... 243
2.6.5. Subroutine userch (Changing Element Face Charge Density Surface Information) ............ 244
2.6.6. Subroutine userfd (Calculating the Complex Load Vector for Frequency Domain Logic) .... 244
2.6.7. Function userpe (Calculating Rotation Caused by Internal Pressure) ................................ 245
2.6.8. Subroutine usrsurf116 (Modifying SURF151 and SURF152 Film Coefficients and Bulk Tem-
peratures) ............................................................................................................................... 246
2.6.9. Subroutine User116Cond (Calculating the Conductance Coefficient for FLUID116) ........... 247
2.6.10. Subroutine User116Hf (Calculating the Film Coefficient for FLUID116) ........................... 247
2.6.11. Subroutine userPartVelAcc (Calculating Particle Velocities and Accelerations of Ocean
Waves) .................................................................................................................................... 248
2.6.11.1. Subroutine userPartVelAccSetup (Initializing Data for Use by the userPartVelAcc
Subroutine) ...................................................................................................................... 249
2.6.11.2. Subroutine userWavHt ......................................................................................... 250
2.6.11.3. Subroutine wvhybl .............................................................................................. 251
2.6.11.4. Subroutine wvargu .............................................................................................. 251
2.6.12. Subroutine userPanelHydFor (Calculating Panel Loads Caused by Ocean Loading) ......... 252
2.6.12.1. Subroutine userOceanRead .................................................................................. 252
2.7. Subroutines for Sharing Data Between User Routines .............................................................. 253
2.7.1. Subroutine userdata (Store Common Block Functionality and Data) ................................ 253
2.7.2. Subroutine usercm.inc (Add Common Block Variables) .................................................... 254
2.8. Running Mechanical APDL as a Subroutine .............................................................................. 254
2.9. Defining Your Own Commands ............................................................................................... 255
2.9.1. Function user01 ............................................................................................................. 256
2.9.2. Function user02 (Demonstrates Offsetting Selected Nodes) ............................................ 256
2.9.3. Function user03 (Demonstrates Using Memory) .............................................................. 258
2.9.4. Function user04 ............................................................................................................. 260
2.9.5. Functions user05 through user10 ................................................................................... 262
2.10. Support Subroutines ............................................................................................................. 262
2.10.1. Function GetRForce (Getting Nodal Reaction Force Values) ............................................ 262
2.10.2. Function GetStackDisp (Getting Current Displacement Values) ...................................... 263
2.10.3. Subroutine ElResultStrt (Getting Load Data from Analysis Results) ................................. 263
2.10.4. Subroutine ElResultGet (Getting Results Values at Selected Points) ................................ 264
2.10.5. Subroutine ElInterp (Finding Element Coordinates) ....................................................... 264
2.11. Access at the Beginning and End of Various Operations ......................................................... 265
2.12. Memory-Management Subroutines ....................................................................................... 266
2.12.1. Using the Memory Manager in a FORTRAN UPF ............................................................. 267
2.12.1.1. Function fAnsMemAlloc (Allocating Space and Returning a Pointer) ...................... 268
2.12.1.2. Function fAnsMemAllocL (Allocating Space and Returning a Pointer - long in-
teger) ............................................................................................................................... 269
2.12.1.3. Function fAnsMemRealloc (Reallocating Space and Returning a Pointer) ............... 269
2.12.1.4. Functional fAnsMemReallocL (Reallocating Space and Returning a Pointer - long
integer) ............................................................................................................................ 269
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. viii
Programmer's Reference
2.12.1.5. Subroutine fAnsMemFree (Deallocating Space) .................................................... 270
2.12.2. Using the Memory Manager in a C or C UPF .............................................................. 270
2.12.2.1. Function cAnsMemAlloc (Allocating Space and Returning a Pointer) ..................... 271
2.12.2.2. Function cAnsMemRealloc (Reallocating Space and Returning a Pointer) .............. 272
2.12.2.3. Subroutine cAnsMemFree (Deallocating Space) .................................................... 272
2.13. Parameter-Processing Subroutines ........................................................................................ 272
2.13.1. Subroutine pardim (Creating a Dimensioned Parameter) ............................................... 272
2.13.2.Subroutine parevl (Finding and Evaluating a Parameter) ................................................ 273
2.13.3. Subroutine pardef (Adding a Parameter) ....................................................................... 273
2.14. Other Useful Functions .......................................................................................................... 274
2.14.1. Using Function RunCommand ...................................................................................... 275
2.14.2. Using the /UNDO Command ........................................................................................ 275
2.14.3. Using the /HOLD command ......................................................................................... 275
3. Accessing the Mechanical APDL Database ................................................................................... 277
3.1. Routines for Selecting and Retrieving Nodes and Elements ...................................................... 278
3.1.1. Function ndnext (Getting the Next Node Number) .......................................................... 278
3.1.2. Function ndprev (Getting the Number of the Previous Selected Node) ............................ 278
3.1.3. Function ndnxdf (Getting the Number of the Next Defined Node) ................................... 278
3.1.4. Function ndsel (Selecting, Unselecting, Deleting, or Inverting a Node) .............................. 279
3.1.5. Function elnext (Getting the Number of the Next Element) ............................................. 279
3.1.6. Function elprev (Getting the Number of the Previous Selected Element) ......................... 279
3.1.7. Function elnxdf (Getting the Number of the Next Defined Element) ................................ 280
3.1.8. Subroutine elsel (Selecting, Unselecting, Deleting, or Inverting an Element) ..................... 280
3.2. Node Information Routines ..................................................................................................... 281
3.2.1. Function ndinqr (Getting Information About a Node) ...................................................... 281
3.2.2. Function getnod (Getting a Nodal Point) ......................................................................... 282
3.2.3. Function putnod (Storing a Node) .................................................................................. 282
3.2.4. Function ndgall (Getting the XYZ/Rotation Coordinates Vector for a Node) ...................... 283
3.2.5. Subroutine ndspgt (Getting the Nodal Solution for a Node of an Element) ....................... 283
3.3. Element Attribute Routines ..................................................................................................... 284
3.3.1. Function elmiqr (Getting Information About an Element) ................................................ 284
3.3.2. Function elmget (Getting an Element's Attributes and Nodes) ......................................... 285
3.3.3. Subroutine elmput (Storing an Element) ......................................................................... 285
3.3.4. Function etyiqr (Getting a Data Item About an Element Type) .......................................... 286
3.3.5. Function etyget (Getting Information About an Element Type) ........................................ 286
3.3.6. Subroutine etyput (Storing Element Type Data) ............................................................... 286
3.3.7. Subroutine echrtr (Getting Information About Element Characteristics) ........................... 287
3.3.8. Subroutine etysel (Selecting, Unselecting, Deleting, or Inverting an Element Type) ........... 287
3.3.9. Function mpinqr (Getting Information About a Material Property) ................................... 288
3.3.10. Function mpget (Getting a Material Property Table) ...................................................... 289
3.3.11. Subroutine mpput (Storing a Material Property Table) ................................................... 289
3.3.12. Subroutine mpdel (Deleting a Material Property Table) .................................................. 290
3.3.13. Function rlinqr (Getting Information About a Real Constant Set) .................................... 290
3.3.14. Function rlget (Getting Real Constant Data) .................................................................. 291
3.3.15. Subroutine rlsel (Selecting or Deleting a Real Constant Set) ........................................... 291
3.3.16. Function csyiqr (Getting Information About a Coordinate System) ................................. 291
3.3.17. Function csyget (Getting a Coordinate System) ............................................................. 292
3.3.18. Subroutine csyput (Storing a Coordinate System) .......................................................... 292
3.3.19. Subroutine csydel (Deleting a Coordinate System) ........................................................ 293
3.3.20. Subroutine userac (Demonstrates Use of Element Attribute Routines) ........................... 293
3.4. Coupling and Constraint Routines ........................................................................................... 293
ix
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Programmer's Reference
3.4.1. Function cpinqr (Getting Information About a Coupled Set) ............................................ 293
3.4.2. Function cpget (Getting a Coupled Set) .......................................................................... 294
3.4.3. Subroutine cpput (Storing a Coupled Set) ....................................................................... 294
3.4.4. Subroutine cpsel (Selecting or Deleting a Coupled Set) ................................................... 295
3.4.5. Function ceinqr (Getting Information About a Constraint Equation Set) ........................... 295
3.4.6. Function ceget (Getting a Constraint Equation) ............................................................... 296
3.4.7. Subroutine ceput (Storing a Constraint Equation) ............................................................ 296
3.4.8. Subroutine cesel (Deleting or Selecting a Constraint Equation) ........................................ 296
3.5. Nodal Loading Routines .......................................................................................................... 296
3.5.1. Function disiqr (Getting Information About Constraints) ................................................. 297
3.5.2. Function disget (Getting a Constraint at a Node) ............................................................. 297
3.5.3. Subroutine disput (Storing a Constraint at a Node) .......................................................... 298
3.5.4. Subroutine disdel (Deleting a Constraint at a Node) ........................................................ 298
3.5.5. Function foriqr (Getting Information About Nodal Loads) ................................................ 299
3.5.6. Function forget (Getting a Nodal Load at a Node) ............................................................ 299
3.5.7. Subroutine forput (Storing a Nodal Load at a Node) ........................................................ 299
3.5.8. Subroutine fordel (Deleting a Nodal Load at a Node) ....................................................... 300
3.5.9. Function ansNodeBodyLoadIqr (Getting Information About a Nodal Body Load) ............. 300
3.5.10. Function ansNodeBodyLoadGet (Getting a Nodal Body Load Value) .............................. 301
3.5.11. Subroutine ansNodeBodyLoadPut (Storing a Nodal Body Load) ..................................... 301
3.5.12. Subroutine ansNodeBodyLoadDel (Deleting a Nodal Body Load) ................................... 301
3.6. Element Loading Routines ...................................................................................................... 302
3.6.1. Function ansElemBodyLoadIqr (Getting Information About an Element Body Load) ......... 303
3.6.2. Function ansElemBodyLoadGet (Getting an Element Body Load Value) ............................ 304
3.6.3. Subroutine ansElemBodyLoadPut (Storing an Element Body Load) .................................. 304
3.6.4. Subroutine ansElemBodyLoadDel (Deleting an Element Body Load) ................................ 304
3.6.5. Function ansElemSurfLoadIqr (Getting Information About an Element Surface Load) ....... 305
3.6.6. Function ansElemSurfLoadGet (Getting an Element Surface Load Value) .......................... 305
3.6.7. Subroutine ansElemSurfLoadPut (Storing an Element Surface Load) ................................ 306
3.6.8. Subroutine ansElemSurfLoadDel (Deleting an Element Surface Load) .............................. 306
3.7. Results Information Routines ................................................................................................... 307
3.7.1. Function dspiqr (Getting Information About Nodal Results) ............................................. 307
3.7.2. Function dspget (Getting a Nodal Result from the Database) ........................................... 307
3.7.3. Subroutine dspput (Storing a Result at a Node) ............................................................... 307
3.7.4. Subroutine dspdel (Deleting a Result at a Node) .............................................................. 308
3.7.5. Function emsiqr (Getting Information About an Element's Miscellaneous Summable
Data) ...................................................................................................................................... 308
3.7.6. Function emsget (Getting an Element's Miscellaneous Summable Data) .......................... 308
3.7.7. Subroutine emsput (Storing an Element's Miscellaneous Summable Data) ....................... 309
3.7.8. Subroutine emsdel (Deleting an Element's Miscellaneous Summable Data) ..................... 309
3.7.9. Function enfiqr (Getting Information About Element Nodal Forces) ................................. 309
3.7.10. Function enfget (Getting an Element's Nodal Forces) ..................................................... 310
3.7.11. Subroutine enfput (Storing an Element's Nodal Forces) ................................................. 310
3.7.12. Subroutine enfdel (Deleting an Element's Nodal Forces) ................................................ 311
3.7.13. Function ensiqr (Getting Information About an Element's Nodal Stresses) ...................... 311
3.7.14. Function ensget (Getting an Element's Nodal Stresses) .................................................. 311
3.7.15. Subroutine ensput (Storing Nodal Stresses at an Element) ............................................. 312
3.7.16. Subroutine ensdel (Deleting an Element's Nodal Stresses) ............................................. 313
3.7.17. Function esfiqr (Getting Information About Element Surface Stress Data) ...................... 313
3.7.18. Function esfget (Getting Element Surface Stress Data) ................................................... 313
3.7.19. Subroutine esfput (Storing Element Surface Stress Data) ............................................... 314
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. x
Programmer's Reference
3.7.20. Subroutine esfdel (Deleting an Element's Surface Stress Data) ....................................... 314
3.7.21. Function engiqr (Getting Information About an Element's Energies) .............................. 314
3.7.22. Function engget (Getting an Element's Energies) .......................................................... 315
3.7.23. Subroutine engput (Storing an Element's Energies and Volume) .................................... 315
3.7.24. Subroutine engdel (Deleting an Element's Energies) ..................................................... 316
3.7.25. Function egriqr (Getting Information About an Element's Nodal Gradients) ................... 316
3.7.26. Function egrget (Getting an Element's Nodal Gradients) ............................................... 317
3.7.27. Subroutine egrput (Storing an Element's Nodal Gradients) ............................................ 317
3.7.28. Subroutine egrdel (Deleting an Element's Nodal Gradients) ........................................... 317
3.7.29. Function eeliqr (Getting Information About an Element's Nodal Elastic Strains) .............. 318
3.7.30. Function eelget (Getting an Element's Nodal Elastic Strains) .......................................... 318
3.7.31. Subroutine eelput (Storing an Element's Nodal Elastic Strains) ....................................... 319
3.7.32. Subroutine eeldel (Deleting an Element's Nodal Elastic Strains) ..................................... 320
3.7.33. Function epliqr (Getting Information About an Element's Nodal Plastic Strains) ............. 320
3.7.34. Function eplget (Getting an Element's Nodal Plastic Strains) .......................................... 320
3.7.35. Subroutine eplput (Storing an Element's Nodal Plastic Strains) ...................................... 321
3.7.36. Subroutine epldel (Deleting an Element's Nodal Plastic Strains) ..................................... 322
3.7.37. Function ecriqr (Getting Information About an Element's Nodal Creep Strains) .............. 322
3.7.38. Function ecrget (Getting an Element's Nodal Creep Strains) ........................................... 322
3.7.39. Subroutine ecrput (Storing an Element's Nodal Creep Strains) ....................................... 323
3.7.40. Subroutine ecrdel (Deleting an Element's Nodal Creep Strains) ...................................... 324
3.7.41. Function ethiqr (Getting Information About an Element's Nodal Thermal Strains) ........... 324
3.7.42. Function ethget (Getting an Element's Nodal Thermal Strains) ....................................... 324
3.7.43. Subroutine ethput (Storing an Element's Nodal Thermal Strains) ................................... 325
3.7.44. Subroutine ethdel (Deleting an Element's Thermal, Initial, and Swelling Strains) ............. 326
3.7.45. Function euliqr (Getting Information About an Element's Euler Angles) ......................... 326
3.7.46. Function eulget (Getting an Element's Nodal Euler Angles) ............................................ 327
3.7.47. Subroutine eulput (Storing an Element's Euler Angles) .................................................. 327
3.7.48. Subroutine euldel (Deleting an Element's Euler Angles) ................................................. 328
3.7.49. Function efxiqr (Getting Information About Element Fluxes) .......................................... 328
3.7.50. Function efxget (Getting an Element Flux) .................................................................... 328
3.7.51. Subroutine efxput (Storing an Element's Fluxes) ............................................................ 329
3.7.52. Subroutine efxdel (Deleting Element Fluxes) ................................................................. 329
3.7.53. Function elfiqr (Getting Information About Element Local Forces) ................................. 329
3.7.54. Function elfget (Getting an Element Local Force) ........................................................... 330
3.7.55. Subroutine elfput (Storing an Element's Local Forces) .................................................... 330
3.7.56. Subroutine elfdel (Deleting Element Local Forces) ......................................................... 330
3.7.57. Function emniqr (Getting Information About Element Miscellaneous Non-summable
Data) ...................................................................................................................................... 331
3.7.58. Function emnget (Getting an Element's Miscellaneous Non-summable Data) ................ 331
3.7.59. Subroutine emnput (Storing an Element's Miscellaneous Non-summable Data) ............. 332
3.7.60. Subroutine emndel (Deleting an Element's Miscellaneous Non-summable Data) ........... 332
3.7.61. Function ecdiqr (Getting Information About Element Current Densities) ........................ 332
3.7.62. Function ecdget (Getting an Element Current Density) .................................................. 333
3.7.63. Subroutine ecdput (Storing an Element's Current Densities) .......................................... 333
3.7.64. Subroutine ecddel (Deleting Element Current Densities) ............................................... 333
3.7.65. Function enliqr (Getting Information About Element Nonlinear Tables) .......................... 334
3.7.66. Function enlget (Getting Element Nonlinear Tables) ...................................................... 334
3.7.67. Subroutine enlput (Storing an Element's Nonlinear Tables) ............................................ 334
3.7.68. Subroutine enldel (Deleting Element Nonlinear Tables) ................................................. 335
3.7.69. Function ehciqr (Getting Information About Calculated Element Heat Generations) ....... 335
xi
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Programmer's Reference
3.7.70. Function ehcget (Getting a Calculated Element Heat Generation) .................................. 336
3.7.71. Subroutine ehcput (Storing an Element's Calculated Heat Generations) ......................... 336
3.7.72. Subroutine ehcdel (Deleting Element Calculated Heat Generations) .............................. 336
4. Subroutines for Your Convenience ................................................................................................ 337
4.1. Input and Output Abbreviations .............................................................................................. 337
4.2. General Subroutines ............................................................................................................... 338
4.2.1. Subroutine dptoch (Retrieve Eight Characters From a Double Precision Variable) ............. 338
4.2.2. Function ppinqr (Obtain Information About Threads) ...................................................... 338
4.2.3. Function pplock (Locking a Thread in Shared Memory) .................................................... 339
4.2.4. Function ppunlock (Unlocking a Thread in Shared Memory) ............................................ 339
4.2.5. Function ppproc (Get the Active Thread Index) ............................................................... 339
4.2.6. Function wrinqr (Obtain Information About Output) ....................................................... 340
4.2.7. Subroutine erinqr (Obtaining Information from the Errors Common) ............................... 340
4.2.8. Subroutine erhandler (Displaying Program Errors) ........................................................... 342
4.2.9. Subroutine intrp (Doing Single Interpolation) ................................................................. 343
4.2.10. Subroutine tranx3 (Processing Geometry for 3-D Line Elements) .................................... 343
4.2.11. Subroutine systop (Stopping a Program Run) ................................................................ 344
4.3.Vector Functions ..................................................................................................................... 344
4.3.1. Function vdot (Computing the Dot Product of Two Vectors) ............................................ 344
4.3.2. Function vidot (Computing the Dot Product of Two Vectors with Increments) .................. 345
4.3.3. Function vsum (Summing Vector Components) .............................................................. 345
4.3.4. Function vmax (Retrieving the Maximum Vector Value at a Given Location) ..................... 345
4.3.5. Function lastv (Retrieving the Position of the Last Nonzero Term in a Double Precision
Vector) ................................................................................................................................... 345
4.3.6. Function izero (Setting an Integer Vector to Zero) ............................................................ 346
4.3.7. Function imove (Assigning Equal Values to Two Integer Vectors) ...................................... 346
4.3.8. Subroutine vzero (Initializing a Vector to Zero) ................................................................ 346
4.3.9. Subroutine vmove (Moving One Vector into Another) ..................................................... 346
4.3.10. Subroutine vimove (Moving One Vector into Another Incrementally) ............................. 346
4.3.11. Subroutine vinit (Assigning a Scalar Constant to a Vector) .............................................. 346
4.3.12. Subroutine viinit (Assigning a Scalar Constant to a Vector Incrementally) ....................... 346
4.3.13. Subroutine vapb (Setting a Vector to Sum of Two vectors) ............................................. 347
4.3.14. Subroutine vapb1 (Combining Two Vectors in One) ....................................................... 347
4.3.15. Subroutine vapcb1 (Multiplying a Vector to a Constant) ................................................ 347
4.3.16. Subroutine vamb (Gets a Third Vector by Subtracting One Vector from Another) ............ 347
4.3.17. Subroutine vamb1 (Subtracting One Vector from Another) ............................................ 347
4.3.18. Subroutine vmult (Multiplying a Vector by a Constant) .................................................. 347
4.3.19. Subroutine vmult1 (Multiplying a Vector by a Constant) ................................................ 348
4.3.20. Subroutine vcross (Defining a Vector via a Cross Product) .............................................. 348
4.3.21. Subroutine vnorme (Normalizing a Three-Component Vector) ....................................... 348
4.3.22. Subroutine vnorm (Normalizing a Vector to Unit Length) ............................................... 348
4.3.23. Function ndgxyz (Getting the X,Y,Z Vector for a Node) ................................................... 349
4.3.24. Subroutine ndpxyz (Storing X,Y,Z for a Node) ................................................................ 349
4.4. Matrix Subroutines .................................................................................................................. 349
4.4.1. Subroutine maxv (Multiplying a Vector by a Matrix) ......................................................... 349
4.4.2. Subroutine maxv1 (Multiplying a Vector by a Matrix) ....................................................... 350
4.4.3. Subroutine matxv (Multiplying a Vector by a Full Transposed Matrix) ............................... 350
4.4.4. Subroutine matxv1 (Multiplying a Vector by a Full Transposed Matrix) ............................. 351
4.4.5. Subroutine matxb (Transposing a matrix) ....................................................................... 351
4.4.6. Subroutine maat (Changing a Matrix Value via Addition, Multiplication, and Transposi-
tion) ....................................................................................................................................... 352
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. xii
Programmer's Reference
4.4.7. Subroutine matba (Updating Matrix Value via Transposition, Multiplications, and Addi-
tion) ....................................................................................................................................... 352
4.4.8. Subroutine matsym (Filling the Upper Triangle from the Lower Triangle) .......................... 353
4.4.9. Subroutine mctac (Transposing a symmetric matrix) ....................................................... 353
4.4.10. Subroutine tran (Transposing a matrix) ......................................................................... 353
4.4.11. Subroutine symeqn (Solving Simultaneous Linear Equations) ........................................ 354
A. Creating External Commands in Linux ............................................................................................. 357
A.1.Tasks in Creating an External Command .................................................................................. 357
A.1.1. Creating Compatible Code ............................................................................................. 357
A.1.2. Creating a Shared Library ............................................................................................... 358
A.1.3. Creating an External Table File ........................................................................................ 359
A.1.4. Setting the ANSYS_EXTERNAL_PATH Environment Variable ............................................. 360
A.1.5. Using External Commands ............................................................................................. 360
A.1.6. Checking External Command Status ............................................................................... 360
A.1.7. Resetting External Commands ....................................................................................... 360
B. Creating External Commands in Windows ........................................................................................ 363
B.1.Tasks in Creating an External Command .................................................................................. 363
B.1.1. Creating Compatible Code ............................................................................................. 363
B.1.2. Creating a Visual Studio Project ...................................................................................... 364
B.1.3. Creating an External Definition File ................................................................................. 364
B.1.4. Creating a Shared Library ............................................................................................... 364
B.1.5. Creating an External Table File ........................................................................................ 365
B.1.6. Setting the ANSYS_EXTERNAL_PATH Environment Variable ............................................. 366
B.1.7. Using External Commands .............................................................................................. 366
B.1.8. Checking External Command Status ............................................................................... 366
B.1.9. Resetting External Commands ........................................................................................ 366
B.1.10. Example: Creating an External Command Using Visual Studio 2017 Professional ............ 367
C. User Material (UserMat) Subroutine Example ................................................................................... 369
C.1. UserMat Example Description ................................................................................................. 369
C.2. UserMat Example Input Data ................................................................................................... 369
C.3. UserMat Example POST26 Output Results ............................................................................... 371
C.4. USERMAT.F List File for This Example ........................................................................................ 371
C.5. Accessing Solution and Material Data ...................................................................................... 377
D. Structural-Thermal User Material (UserMat, UserMatTh) Example ...................................................... 379
D.1. Example Description ............................................................................................................... 379
D.2. Example Input Data ................................................................................................................ 379
E. Fully Coupled Wind Turbine Example in Mechanical APDL ................................................................ 383
E.1. Implementing a Fully Coupled Wind Turbine Analysis .............................................................. 383
E.2.Theory .................................................................................................................................... 384
E.3. Compiling a Custom Version of Mechanical APDL .................................................................... 385
E.4. Performing a Wind Coupled Analysis ....................................................................................... 386
E.4.1.The Wind Coupling Process ............................................................................................. 386
E.4.2. Data Exchange Routines ................................................................................................. 386
E.4.3. Important Analysis Notes ................................................................................................ 388
E.5. Example Analysis Using Provided “WindProg” Example for Aeroelastic Coupling ....................... 389
E.6. References .............................................................................................................................. 391
xiii
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
Programmer's Reference
Release 2020 R2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information