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:

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:

If you are running in a distributed-memory parallel environment, you must set the ANS_USER_PATH environment variable to the working directory and include the name of the head compute node:

set ANS_USER_PATH=\\headnode\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\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.

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

findstr /I debug *.out

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\v242\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 2024 R2 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 14.10.25027.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 ansys242 to use your newly generated
      user shared library.

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

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

If you are running in a distributed-memory parallel environment, you need to include the name of the head compute node when specifying the working directory:

set ANS_USER_PATH=\\headnode\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 Mechanical APDL 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.

The ANS_ADMIN procedure for compiling and linking UPFs on Windows systems creates a custom executable. Any of the user routines residing in Program Files\ANSYS Inc\V242\ansys\customize\user\ can be linked via this method. The executable can run in a shared-memory parallel (SMP) environment or a distributed-memory parallel (DMP) environment.

Perform the ANS_ADMIN procedure in either of the following ways:

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

Routines linked via the /UPF method  —  Routines linked via the /UPF method (listed in Using the /UPF Command) cannot be relinked via the ANS_ADMIN242 utility nor the ANSCUST.bat script. Those routines have reserved DLL names and are built only by issuing the /UPF command or by running the ANSUSERSHARED.bat script.

Using the ANS_ADMIN242 utility  —  To link your changes into Mechanical APDL, select the Relink MAPDL option in the ANS_ADMIN242 utility.

This procedure prompts you for the versions that you intend to relink, then compiles all Fortran files (.f), C files (.c), and C++ files (.cpp) in the Program Files\ANSYS Inc\V242\ansys\custom\user\<platform> directory.

After compiling, the procedure loads all object files (.obj), along with the default Mechanical APDL objects and libraries, and creates the custom executable.

The executable file created is named ansys.exe and resides in your specified location. (A custom Mechanical APDL executable must be named ansys.exe due to shared libraries.)

Creating a relinked version of Mechanical APDL via ANSCUST.bat  —  On Windows systems, attempting to create a relinked version of Mechanical APDL via the ANSCUST.bat script instead of the ANS_ADMIN242 utility may generate error messages.

The messages may indicate that object files have been created but that the Mechanical APDL executable has not been created, or that some libraries necessary to complete the link cannot be found. Typically, the errors appear because required compiler environment variables are not set. To avoid such errors, use the following workaround when relinking Mechanical APDL via ANSCUST.bat:

Running a custom Mechanical APDL executable  —  After relinking the Mechanical APDL executable, run the program using either of these methods: