This section describes how to create UPFs on a Linux operating system. See the next section if you are working on a Windows operating system.
To convert your Fortran code into an object file, you must install the Intel compiler. To convert your object files into a shared object, you must also install the GCC compiler. For information about the required compilers for Linux systems, see Compiler Requirements for Linux Systems in the Ansys, Inc. Installation Guides.
Note: You must install all the compilers specified in the Installation Guide specific to your operating system to use these user-programmable features, including GNU GCC 8.2.0. This specific compiler can be downloaded from the Ansys, Inc. customer site. See Downloading and Installing the GCC Compiler for details. 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.
There are three methods that you can use to link your custom routines into Mechanical APDL:
| Using the /UPF Command |
| Using the ANSUSERSHARED script to Create a Shared Library |
| Using the ANS_ADMIN Utility |
Find the source files for the user routines in the following directory:
/ansys_inc/v251/ansys/customize/user/
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 /UPF command offers the simplest method for linking user-programmable features into Mechanical APDL. To link a user routine named filename.ext (that must reside in the current working directory), issue the command:
/UPF, filename.extTo 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, Mechanical APDL is automatically relinked for every /UPF command.
You can issue one or more /UPF commands anywhere in your input file as many times as needed to include multiple user routines in the relinked version. Any user routine can be linked using this method.
When you run a user-linked version of the program by this method, the output includes:
The following note where
nindicates the number of routines specified by /UPF commands.NOTE – This Mechanical APDL version was linked by /UPF with n user supplied routine(s).The routines that have been linked.
Example Using Mixed Languages
For a simple, automated test that verifies whether compilers are correctly installed and
configured, see the
/ansys_inc/v251/ansys/custom/user/<platform>/Examples
directory. It contains:
An example that uses the /UPF command method to link user routines that are written in mixed languages (Fortran, C, C++).
A README.txt file with complete instructions on running this example.
You can also set up UPFs on some Linux systems through a shared 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 shared library should reside in your working directory. To compile all *.f, *.c, and *.cpp routines, issue the following command:
/ansys_inc/v251/ansys/customize/user/ANSUSERSHARED
If the compilation was successful, you are asked if a shared file is to be created. Choose to create a shared library named libansuser.so.
To use the libansuser.so library, you must set the ANS_USER_PATH environment variable its working directory by issuing one of the following commands, depending on the Linux shell you are using:
setenv ANS_USER_PATH workingdirectoryor
export ANS_USER_PATH=workingdirectoryWhen you run a user-linked version of Mechanical APDL, the output echoes the value of ANS_USER_PATH and will include the following:
NOTE: This Mechanical APDL version was linked by Licensee
To return to the original version of Mechanical APDL, unset the ANS_USER_PATH environment variable.
To point to a shared library specific to Release 2025 R1, you can use another environment variable, ANS_USER_PATH_251, which supersedes ANS_USER_PATH. This lets you set up and use more than one shared library containing UPFs. To return to the shared library specified by ANS_USER_PATH, simply unset the ANS_USER_PATH_251 environment variable.
Use the ANSUSERSHARED script as a template to try compilers that are not supported by Ansys, Inc., such as the GNU compilers. Edit the ANSUSERSHARED script, making changes to the appropriate platform logic. Note that if you do use compilers other than those listed in the Ansys, Inc. Installation Guide specific to your operating system, you will need to debug them yourself (that is, find missing libraries, unsatisfied externals, etc.). Ansys, Inc. does not provide assistance for customers using unsupported compilers or if the resulting objects are not compatible with the executable(s) as distributed.
To create a custom Mechanical APDL executable for frequent use, modify the subroutines the directory /ansys_inc/v251/ansys/customize/user/ and select the Relink MAPDL option from ANS_ADMIN251 utility to link these changes.
The Relink MAPDL option:
compiles all Fortran files (files ending with .f), C files (files ending with .c), and C++ files (files ending in .cpp) in the current working directory.
loads all object files (files ending with .o) along with the default Mechanical APDL objects and libraries in /ansys_inc/v251/ansys/customize/user/<
platform>, where <platform> is replaced by the folder representative of your operating system.names the newly created executable file in the working directory ansyscust.e.
When you run a user-linked version of Mechanical APDL, the output includes the following:
NOTE: This Mechanical APDL version was linked by Licensee
If you intend to run the linked version of Mechanical APDL in a distributed environment (for example, on a cluster), the executable (ansyscust.e) must reside in the same directory path on all machines. However, you need to link it on only one machine and then copy the executable to the other machines.
To link UPFs on a Linux system, the Ansys-built version of the GCC 8.2.0 compiler is required. You must download this compiler from the Ansys customer site and extract the necessary files using these steps:
From the Ansys customer site, www.ansys.com/customercommunity, click .
Select the Linux x64 operating system.
Select Primary Packages from the Select Download Type drop-down menu.
Expand the Tools menu.
Click the GCC Compiler download option.
Select your desired download directory and click Save.
This will download the compressed tar file GCCCOMPILER_820_LINX64.tgz.
Create a folder to contain the contents of the tar file.
Extract the file within the location created in step 7 using the appropriate tar command. For example:
tar zxf GCCCOMPILER_820_LINX64.tgz
Add the location to your PATH, or set ANS_GCC_PATH for access to the GCC 8.2.0 compiler. For example:
setenv PATH <installed_location>/bin:$PATH (for csh/tcsh shell) export PATH=<installed_location>/bin:$PATH (for sh/bash shell)
or
setenv ANS_GCC_PATH <installed_location>/bin (for csh/tcsh shell) export ANS_GCC_PATH=<installed_location>/bin (for sh/bash shell)
The GCC version should display gcc (ansys-20190911) 8.2.0. See Special Considerations for SUSE 15 SP2.
For SUSE Linux Enterprise Server 15 SP2, the GCC 8.2.0 compiler is incompatible. Use the system-required GCC instead. Verify that both the C compiler (GCC) and the C++ compiler (G++) are available for use. For access to the system GCC compiler, add the location to your PATH or set ANS_GCC_PATH as shown below.
The standard location for the system GCC is /usr/bin.
setenv PATH /usr/bin:$PATH (for csh/tcsh shell) export PATH=/usr/bin:$PATH (for sh/bash shell)
or
setenv ANS_GCC_PATH /usr/bin (for csh/tcsh shell) export ANS_GCC_PATH=/usr/bin (for sh/bash shell)
If GCC is set to a version other than the system GCC via PATH or ANS_GCC_PATH, you may see this error:
/usr/lib64/libpthread_nonshared.a(pthread_atfork.oS): unable to initialize decompress status
for section .debug_info
/usr/lib64/libpthread_nonshared.a: error adding symbols: File format not recognized