1.9. Compiling and Linking UPFs on Linux Systems

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

The source files for the user routines reside in the following subdirectory: /ansys_inc/v182/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 ANSYS, Inc. Linux Installation Guide lists the compilers that are required for specific platforms.

1.9.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 a user routine (filename.ext) that you want to link. The specified routine must reside in the current working directory.

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, Mechanical APDL will be relinked automatically.

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. 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 – 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++):

/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.9.2. Creating a Shared Library

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/v182/ansys/customize/user/ANSUSERSHARED

If the compile was successful, you will be asked if a shared file is to be created. Choose Yes to create a shared library named libansuser.so.

To use this library, set the ANS_USER_PATH environment variable to point to the working directory where the libansuser shared library resides. Use one of the following commands, depending on the Linux shell you are using:

setenv ANS_USER_PATH workingdirectory

or

export ANS_USER_PATH=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 ANSYS, unset the ANS_USER_PATH environment variable.

ANSYS, Inc. recommends using the ANSUSERSHARED script as a template to try compilers that are not supported by ANSYS, Inc., such as the GNU compilers. To do so, 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 Installation and Configuration Guide specific to your operating system, you will need to debug (i.e., find missing libraries, unsatisfied externals, etc.) them yourself. 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.

1.9.3. Using the ANS_ADMIN Utility

As mentioned previously, the source files for the user routines reside in subdirectory /ansys_inc/v182/ansys/customize/user/. If you modify any of these subroutines, you can select the Relink ANSYS option from ANS_ADMIN182 utility to link these changes. This method creates a custom Mechanical APDL executable.

The Relink ANSYS 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. The procedure then loads all object files (files ending with .o) along with the default Mechanical APDL objects and libraries in /ansys_inc/v182/ansys/customize/user/<platform>. For Distributed ANSYS the location is: /ansys_inc/v182/ansys/customize/user/<platform>/dis/native, where <platform> is replaced by the folder representative of your operating system. The new executable file created will be named ansyscust.e and will reside in the working directory.

When you run a user-linked version of Mechanical APDL, the output includes the following:

NOTE:  This ANSYS 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 systems. However, you need to link it on only one system; you can then copy the executable to the other systems.


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