1.10. Compiling and Linking UPFs on Windows Systems

There are three methods that you can use to link your custom routines into the Mechanical APDL program:

Use the /UPF command
Create a dynamic-link library
Use the ANS_ADMIN Utility

The source files for the user routines reside in the following subdirectory: Program Files\ANSYS Inc\V182\ansys\customize\user\.

The user programmable features are loaded onto the system only if you perform a custom installation and choose to install the customization tools. If you intend to modify any of the user routines, make a duplicate copy of the Program Files\ANSYS Inc\V182\ansys\customize\user\ directory to preserve the original files for later use, if necessary.

For all three methods, you can write your user routines in one language or a combination of languages (Fortran, C, and C++). Note that when using a combination of languages, you are responsible for the calling interfaces between languages (see Programming in Languages Other than Fortran).

The ANSYS, Inc. Windows Installation Guide lists the compilers that are required for Windows systems.


Note:  You will need all the compilers specified in the Installation Guide specific to your operating system to use these user programmable features. ANSYS, Inc. does not provide assistance if customers are using unsupported compilers, or if the resulting objects are not compatible with the Mechanical APDL executable(s) as distributed.


Before linking UPFs, make sure that the INCLUDE, LIB, and PATH environment variables are set correctly for the required C/C++ and Intel Fortran compilers.

Visual Studio 2012 Professional Update 4 is also required for linking user programmable features on Windows platforms. Before using any of the methods described below for linking UPFs, open the following Command Prompt window if you have Visual Studio 2012 Professional installed:

Start > Microsoft Visual Studio 2012 > Visual Studio Tools > Visual Studio 2012 x64 Native Tools Command Prompt


Note:  For all three linking methods, you might have issues with write/modify access if you use the default working directory: Program Files\ANSYS Inc\V182\ansys\custom\user\. If the linking operation errors out or fails, try running the required applications as an administrator by right clicking and choosing “Run as administrator” while launching each application.


1.10.1. Using the /UPF Command

The /UPF command offers the simplest method for linking user programmable features into Mechanical APDL. The format of the command is:

/UPF, RoutineName

where RoutineName is the name of the user routine (filename.ext) that you want to link. The specified routine must reside in the current working directory.

Following are prerequisites for using the /UPF command method on a Windows system:

  • A script named findUPF.bat is used to detect the /UPF command. You must include the path to this script in your system PATH variable. This script is typically located in Program Files\Ansys Inc\V182\ansys\bin\<platform> where <platform> is a directory that uniquely identifies the hardware platform version: “Winx64” for 64-bit Windows.

  • Before starting Mechanical APDL, you must set the ANS_USE_UPF environment variable to TRUE. This causes the program to search for /UPF in the input file. This environment variable is required only on Windows systems and only when using the /UPF command method for linking UPFs. The ANS_USE_UPF environment variable should not be set when using other methods to link UPFs.

To use this method start Mechanical APDL in batch mode and include one or more /UPF commands in the specified input listing. When the program reads the input and detects /UPF, the appropriate DLL is created.

You can include /UPF anywhere in your input file, and you can repeat /UPF as many times as needed to include multiple user routines in the relinked version. The following user routines can be linked using this method:

UANBEG
UANFIN
UCNVRG
UELMATX
UITBEG
UITFIN
ULDBEG
ULDFIN
USER01 -USER10
USERCNPROP
USERCREEP
USERCV
USERCZM
USERELEM
USERFLD
USERFRIC
USERFX
USERHYPER
USERINTER
USERMAT
USERMATTH
USEROU
USERSWSTRAIN
USER_TBELASTIC
USERWEAR
USOLBEG
USOLFIN
USRCAL
USREFL
USRSHIFT
USRSURF116
USSBEG
USSFIN
UTIMEINC

To use the resulting DLL library, set the ANS_USER_PATH environment variable to the working directory where the UPF DLL library resides:

set ANS_USER_PATH=workingdirectory

If you are running in a distributed memory parallel environment (Distributed ANSYS), you must include the name of the master node when specifying the working directory:

set ANS_USER_PATH=\\masternode\workingdirectory

When you run a user-linked version of the program by this method, the output includes this message:

NOTE – This ANSYS version was linked by /UPF with n user supplied routine(s).

where n indicates the number of routines specified by /UPF commands. The routines that have been linked will be included in the output listing.

Example Using Mixed Languages

The following directory contains an example of using the /UPF command method to link user routines that are written in mixed languages (Fortran, C, C++):

Program Files\ANSYS Inc\V182\ansys\custom\user\<platform>\Examples

The README.txt file in this directory contains complete instructions on running this example. This is a simple, automated test that verifies whether compilers are correctly installed and configured.

1.10.1.1. Using the /UPF Command on a Windows HPC Server System

Running a distributed memory parallel (Distributed ANSYS) solution on a Windows HPC Server system is more involved than running across a simple Windows cluster. You can use the steps described here to test the /UPF command on a Windows HPC Server system. Several files are included with the ANSYS, Inc. software installation for use in this example.

Before you begin, Visual Studio 2012 Professional and Intel Fortran 15.0 must be on the "master" compute node (which is usually not the head node).

The files needed for this example can be found in the following directory:

C:\Program Files\ANSYS Inc\v182\commonfiles\MPI\WindowsHPC\UPF

These include two user routines, a Mechanical APDL input file, and two files required by the HPC Job Manager:

usercreep.F
usermat.F
slupf.inp
RUNANSYS_UPF.xml
runansysupf.bat

Copy these files to:

C:\Temp\%USERNAME%

You will need to modify the value of the ANS_USER_PATH environment variable in RUNANSYS_UPF.xml to the appropriate location where the UPF DLL library resides.

Submit RUNANSYS_UPF.xml to the HPC Job Manager. When the job is complete, run the following commands from a Command Prompt window:

clusrun /exclude:%CCP_SCHEDULER% copy /y C:\Temp\%USERNAME%\Work\*.out \\%CCP_SCHEDULER%\Temp\%USERNAME%

findstr /I debug *.out

If the test worked correctly, this should display many lines of debug from all output files.

For more information on running Distributed ANSYS under Windows HPC Server, see Configuring Distributed ANSYS in the Parallel Processing Guide.

1.10.2. Creating a Dynamic-link (DLL) Library

You can also set up UPFs on Windows systems by using a DLL library. All Fortran files (files ending with .F), C files (files ending with .c), and C++ files (files ending in .cpp) that you want to include in your DLL library should reside in your working directory. To compile all *.F, *.c, and *.cpp routines, issue the following command:

\Program Files\Ansys Inc\v182\ansys\custom\user\<platform>\ANSUSERSHARED.bat

After you issue ANSUSERSHARED.bat, the output will display the options for building the DLL library. The first portion of the output is shown below:

This is the ANSYS 18.2 ANSUSERSHARED script.  It is used
to build a DLL of User Programmable Features for the program.

           NOTE:  The user subroutine source file(s) are expected to
                  reside in this directory.

 Enter one of the following choices to create your
 User Programmable Feature DLL:

The user routines that are supported by this method will appear in a list. (These are the same user routines as listed above for the /UPF command method.) Enter the user routine name you wish to include. As an example, if you enter USERMAT the following output will display and prompt you to select another option:

You chose USERMAT
Microsoft (R) Incremental Linker Version 11.00.61030.0
Copyright (C) Microsoft Corporation.  All rights reserved.

-out:UserMatLib.dll
-def:UserMatLibex.def
-dll
-machine:AMD64
-map
-manifest
-manifestfile:UserMatLib.dll.intermediate.manifest
-defaultlib:ANSYS.lib
-defaultlib:bufferoverflowU.lib
*.obj
   Creating library UserMatLib.lib and object UserMatLib.exp

      ************************************************************************

      UserMatLib.dll has been successfully built.

      Set the environment variable ANS_USER_PATH to the directory where the
      UserMatLib.dll resides and run ansys182 to use your newly generated
      user shared library.

      ************************************************************************

After you have selected all desired user routines, press Enter to quit.

To use the resulting DLL library, set the ANS_USER_PATH environment variable to point to the working directory where the UPF DLL library resides. Use the following command:

set ANS_USER_PATH=workingdirectory

If you are running in a distributed memory parallel environment (Distributed ANSYS), you need to include the name of the master node when specifying the working directory:

set ANS_USER_PATH=\\masternode\workingdirectory

When you run a user-linked version of Mechanical APDL, the output echos the value of ANS_USER_PATH and will include the following:

NOTE:  This ANSYS version was linked by Licensee

To return to the original version of Mechanical APDL, return the ANS_USER_PATH environment variable to its original value.

Multiple UPF DLLs can be created via the ANSUSERSHARED.bat script but must exist in the same directory as designated by the ANS_USER_PATH environment variable.

1.10.3. Using the ANS_ADMIN Utility

The ANS_ADMIN procedure for compiling and linking UPFs on Windows Systems creates a custom executable. This executable can be used to run in a shared memory parallel (SMP) environment or a distributed memory parallel environment (Distributed ANSYS).

As mentioned previously, the source files for the user routines reside in subdirectory Program Files\ANSYS Inc\V182\ansys\customize\user\ .

If you modify any of the user routines, move them to the folder(s) they are linking in. By default this folder is:

Program Files\Ansys Inc\V182\ansys\custom\user\<platform>

Where <platform> is a directory that uniquely identifies the hardware platform version: “Winx64” for 64-bit Windows.


Note:  The user routines listed in Using the /UPF Command cannot be linked with the ANS_ADMIN utility or the ANSCUST.bat script. These user routines have reserved DLL names and must be built using either the /UPF command or the ANSUSERSHARED.bat script.


You can select the Relink ANSYS option from the ANS_ADMIN182 utility to link these changes into Mechanical APDL. This procedure will ask which versions you intend to relink and then will compile all Fortran files (files ending with .F), C files (files ending with .c), and C++ files (files ending in .cpp) in the Program Files\ANSYS Inc\V182\ansys\custom\user\<platform> directory. The procedure then loads all object files (files ending with .obj), along with the default Mechanical APDL objects and libraries and creates custom executables. The executable file(s) created will be named ansys.exe and will reside in the folders described above.


Caution:  When creating custom executables, they must be named ansys.exe. This requirement is due to shared library usage.



Note:  On any Windows system, if you are attempting to create a relinked version of Mechanical APDL by using ANSCUST instead of using the ANS_ADMIN182 utility (as recommended above), error messages may occur. These messages may state that object files have been created, but the Mechanical APDL executable has not been created; or the errors may state that some libraries necessary to complete the link cannot be found. These errors usually indicate that required compiler environment variables are not set. To avoid these errors, use the following workaround when relinking Mechanical APDL with ANSCUST:

  • Pick Start > Microsoft Visual Studio 2012 > Visual Studio Tools > Visual Studio 2012 x64 Native Tools Command Prompt, which should open a new command prompt window.

  • In this command prompt window, issue the drive letter and all the necessary cd commands to move to the directory where the customized files exist (example: C:\Program Files\ANSYS Inc\V182\ansys\custom\user\).

  • Type ANSCUST in this command window. The process of creating the new user-customized Mechanical APDL version begins.


After relinking the ANSYS executable, the program can be executed by either of the following two methods:

  1. To execute the relinked version of the ANSYS program:

    • Click Start>Programs>ANSYS 18.2>Mechanical APDL Product Launcher

    • In the launcher, select the Customization/Preferences tab, then browse to the path which contains the relinked ansys.exe. Select other desired options then pick Run to execute the customized ansys.exe.

  2. To execute the relinked ansys.exe from a Command Prompt window, use one of the following commands.

    • Interactive:

      ansys182 -p <product variable> -g -custom <path> 
    • Batch:

      ansys182 -b -p <product variable> -j jobname -i <input file> -o <output file> -custom <path> 

    where “path” indicates the full path to the relinked ansys.exe.


Note:  The -custom option must be the last option at the end of the command line.



Note:  The commands above are for the SMP version of Mechanical APDL. See Activating Distributed ANSYS in the Parallel Processing Guide for instructions on running Distributed ANSYS.



Note:  Output from a user-linked version contains the following statement:

This ANSYS version was linked by Licensee


Release 18.2 - © ANSYS, Inc. All rights reserved.