7.1 User Programmable Features (UPFs)The ANSYS program's open architecture allows you to link it to your own FORTRAN routines and subroutines. In fact, some of the ANSYS features you see today as "standard" offerings originally started as user-programmed features. This chapter provides a basic introduction to UPFs. For detailed information, see the Guide to ANSYS User Programmable Features. 7.1.1 What Are UPFs?User programmable features (UPFs) are ANSYS capabilities for which you can write your own FORTRAN routines. UPFs are only available in the ANSYS/Multiphysics, ANSYS/Mechanical, ANSYS/Structural, ANSYS/PrepPost, and ANSYS/University (Research Faculty/Student version) products. UPFs allow you to customize the ANSYS program to your needs, which may be a user-defined material behavior option, a user element, a user-defined failure criterion (for composites), and so on. You can even write your own design optimization algorithm that calls the entire ANSYS program as a subroutine. Note-Using UPFs requires extreme care and thought on your part. By linking in your own FORTRAN routines, you are creating a customized, site-dependent version of the ANSYS program. UPFs cannot be used when you are running ANSYS on parallel systems. In addition, use of UPFs is a non-standard use of the ANSYS program, one that ANSYS Inc.'s Quality Assurance verification testing program does not cover. You are responsible for verifying that the results produced are accurate and that the routines you link to ANSYS do not adversely affect other, standard areas of the program. 7.1.2 How to Use UPFsUPFs can range from a simple element output routine for customized output to a much more complex user element or user optimization algorithm. Therefore, it is difficult to present the procedures without describing specific programming details. This section presents a general sequence of steps to follow. The Guide to ANSYS User Programmable Features contains more detail on UPFs. A typical UPF involves the following steps: 1. Design and program the desired user routine in FORTRAN 77. The source codes for all user routines are available on your ANSYS distribution medium. Most of them demonstrate at least simple functionality, so you should obtain a printout of the appropriate routine before you begin programming. 2. Compile and link your user routine into the ANSYS program. The ANSYS Installation and Configuration Guide describes how to do this on your system. 3. You may want to verify that the changes you have made do not affect other, standard ANSYS features. You can do this, for example, by running a set of ANSYS Verification Manual problems. Input for these problems is also available on your ANSYS distribution medium. 4. Verify the user routine using whatever procedures you feel are adequate. Remember that this is your responsibility. The ANSYS program activates some UPFs, such as user elements, automatically when you use them. For example, to activate a user element, all you need to do is specify it as one of the element types in the model (ET command or menu path Main Menu>Preprocessor>Element Type>Add/Edit/Delete), set the element type attribute pointer (TYPE command or menu path Main Menu>Preprocessor> -Attributes-Define>Default Attribs), and define elements using the solid modeling [AMESH, VMESH, etc.] or direct generation [ET, etc.] method. For some other UPFs, you need to take an additional action to activate them. That is, you need to issue the USRCAL command or pick one of the following menu paths: Main Menu>Preprocessor>Loads>-Load Step Opts-Other>User Routines or Main Menu>Solution>-Load Step Opts-Other>User Routines. If you fail to do this, standard ANSYS logic will be used by default. For example, when you apply a convection load, the default is to use standard ANSYS logic even if you have a user convection routine linked in. You must activate the appropriate user routine with the USRCAL command if you want the user convection routine to be used. Refer to the USRCAL command description for a list of user routines affected by the command. Use the NSVR command to define the number of extra variables that need to be saved for such user-programmable element options as user plasticity. (The NSVR command has no equivalent GUI path.) Another useful command is /UCMD, which allows you to make your own command out of a user routine. (The /UCMD command has no GUI equivalent.) Suppose you link in a user routine for a parabolic distribution of pressure. If you name the routine USERnn (where nn = 01 to 10), you can create your own command to call the routine: /UCMD,PARAB,1PARAB now becomes a valid ANSYS command that simply calls the user routine USER01. You can call up to ten such user routines as commands. By including /UCMD commands in your start-up file (START5x.ANS), you can make the user routines available in all your ANSYS sessions. 7.1.3 A Brief Description of the Types of UPFs Currently AvailableUser element-This is a user-written element type you can add to the ANSYS element library and use as a "regular" element. You can create up to six independent element types (USER100 - USER105). Example copies of the routines for MASS21, the structural mass element, and LINK8, the 3-D spar, are included in ANSYS distribution media for demonstration purposes. User element coordinate system orientation-This is available for the following element types: SHELL43, SHELL63, SHELL91, SHELL93, SHELL99, SHELL181, SOLID46, and SOLID64. For the layered elements (SOLID46, SHELL91, and SHELL99), you can also customize the orientation of a given layer. User real constants-Elements COMBIN7 and COMBIN37 allow the input real constants to be modified based on your own nonlinear function. User thickness and stresses-This is available for SHELL181. User coefficient of friction-This is available for general contact elements CONTAC48 and CONTAC49. User plasticity law-This allows you to calculate plastic strains and form the tangent stress-strain matrix at an integration point based on your own plasticity law. User creep equation-This allows you to specify your own creep equation. User swelling law-If you need to account for swelling in an analysis (such as due to neutron bombardment), you must write the appropriate swelling law as a user routine. No built-in swelling laws are available in the ANSYS program. User hygrothermal growth-This allows you to induce growth caused by moisture content, and is available for the SHELL91 element. User hyperelasticity-This is available for hyperelastic elements HYPER56, HYPER58, HYPER74, and HYPER158. User failure criteria-This is available for the layered elements SOLID46 and SHELL99. Up to six user-defined failure criteria can be supplied. User viscosity-You can define viscosity as a function of pressure, temperature, position, time, velocity, and velocity gradients for FLUID141 and FLUID142. User loads-Body loads such as temperatures, heat generations, and fluences (such as neutron flux), as well as surface loads such as pressures, convections, heat fluxes and charge density may be defined by way of user-written logic. User load vector-This allows you to create a complex load vector for the frequency domain logic of the PIPE59 element. You can use it to represent hydrodynamic forces. ANSYS as a subroutine-You can call the entire ANSYS program as a subroutine in your own program, such as a user-written design optimization algorithm. User optimization-You can replace the ANSYS optimization logic with your own algorithm and termination logic. User access at the beginning and end of each ANSYS run solution, load step, substep, and equilibrium iteration-This allows you to evaluate results and perform any desired calculations during solution. 7.2 Non-standard Uses of the ANSYS ProgramThe ANSYS program goes through a rigorous verification testing plan before its release. You can be reasonably assured of obtaining good results when you exercise documented features using "standard," recommended procedures. However, in some situations you may need to employ non-standard techniques-techniques that have not been or cannot be fully tested at ANSYS, Inc. because of their very nature, such as user-programmable features. Be aware that verifying the results in such cases is your responsibility. 7.2.1 What Are Non-standard Uses?The results of non-standard uses of the ANSYS program cannot be predicted. Therefore, ANSYS, Inc.'s Quality Assurance verification program cannot fully cover such uses. ANSYS, Inc. does not discourage non-standard uses, but you should exercise caution and your engineering judgment in these situations. For example, if you write your own user element and use it in an ANSYS analysis, the results depend primarily on how well the element was programmed. You must verify the results in such cases, and make sure that other, standard areas of the program are not adversely affected. The following is a partial list of non-standard ANSYS features and uses: User programmable features (UPFs)-writing your own user routines, linking them into the ANSYS executable, and using them in an analysis. UPFs are described earlier in this chapter. Reading into the ANSYS program an ANSYS file which was created or modified external to the ANSYS program, for example, a results file or a superelement file created by you or by another program. High-risk capabilities such as the following: Changing element real constants in SOLUTION, between load steps. Depending on the element type being used, the element may not properly use the updated real constant value. Deactivating the cross-reference checking of the solid model [MODMSH,NOCHECK] (Main Menu>Preprocessor>Checking Ctrls>Model Checking). Turning off element shape checking [SHPP,OFF] (Main Menu> Preprocessor>Checking Ctrls>Shape Checking). Using undocumented features, such as an element option not documented in the ANSYS Elements Reference or a command argument not mentioned in the ANSYS Commands Reference. Undocumented features, by definition, are "unofficial," unverified, and should be used with caution. If the ANSYS program can detect the use of a non-standard feature, it will often issue a warning message to that effect. 7.2.2 Some GuidelinesFollow these guidelines when you need to use the ANSYS program in a non-standard manner: Use your engineering judgment and carefully review the results of the analysis. Do not assume that other, standard areas of the program are not affected. Run a few test problems to verify this. If you need to obtain customer support on an analysis involving non-standard use of the program, be sure to mention the nature and extent of the non-standard feature th