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/v242/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.
Note: You will need 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.
The /UPF command offers the simplest method for linking user-programmable features into Mechanical APDL. The format of the command is:
/UPF, RoutineNamewhere 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 Mechanical APDL 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/v242/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.
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/v242/ansys/customize/user/ANSUSERSHARED
If the compile was successful, you will be asked if a shared file is to be created. Choose 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 workingdirectoryor
export ANS_USER_PATH=workingdirectoryWhen 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 Mechanical APDL version was linked by Licensee
To return to the original version of Mechanical APDL, unset the ANS_USER_PATH environment variable.
You can use another environment variable, ANS_USER_PATH_242, to point to a shared library specific to Release 2024 R2. ANS_USER_PATH_242 supersedes ANS_USER_PATH. This allows you to set up and use more than one shared library containing UPFs. To change back to the shared library specified by ANS_USER_PATH, simply unset the ANS_USER_PATH_242 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, Inc. Installation Guide specific to your operating system, you will need to debug (that is, 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.
As mentioned previously, the source files for the user routines reside in subdirectory /ansys_inc/v242/ansys/customize/user/. If you modify any of these subroutines, you can select the Relink MAPDL option from ANS_ADMIN242 utility to link these changes. This method creates a custom Mechanical APDL executable.
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. The procedure then loads all object files (files ending with
.o) along with the default Mechanical APDL objects and libraries in
/ansys_inc/v242/ansys/customize/user/<platform>,
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 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 systems. However, you need to link it on only one system; you can then copy the executable to the other systems.
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
In order to link UPFs on a Linux system, the Ansys-built version of the GCC 8.2.0 compiler is required. Therefore, 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.
Special Considerations for SUSE 15 SP2
For SUSE Linux Enterprise Server 15 SP2, the GCC 8.2.0 compiler is not compatible. Therefore, the system-required GCC should be used instead. 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