Coding a Python UPF is different from using a compiled language like C/C++ or Fortran, mainly in terms of the API. Because the gRPC technology is used to handle the communication and the exchange of data between the Python process and the Mechanical APDL process, you need to understand the way this feature handles the serialization/deserialization of data.

The main difference is in the subroutine arguments. Instead of having a full list of arguments as described for each of the subroutines, there are only two: the request object (for inputs), and the response object (for outputs). If an argument is both input and output of the subroutine, it will be part of both objects.

The description of the request object and the response object can be found in the MapdlUser.proto file stored in this installation directory:

First, create a Python file starting from this template:

import grpc
import sys
from mapdl import *

class MapdlUserService( MapdlUser_pb2_grpc.MapdlUserServiceServicer ):

#   #################################################################
    def UAnBeg( self, request, context):

        print( " ======================================= ")
        print( " >> Inside the PYTHON UAnBeg routine  << ")
        print( " ======================================= \n")

        response = google_dot_protobuf_dot_empty__pb2._EMPTY()
        return response

if __name__ == '__main__':
    upf.launch( sys.argv[0])

Note that the Mechanical APDL application automatically installs a Mechanical APDL Python package (a set of Python functions to handle the connection between Mechanical APDL and the Python environment). Each Python UPF must be imported, as noted by:

from mapdl import *

The above example redefines the UAnBeg routine and prints a customized banner. This file must be in the same directory as the input file.

To use this Python UPF, you must add the Mechanical APDL /UPF command to your input file:

/UPF,my_upf.py

! The UAnBeg UPF must be activated by using the USRCAL APDL command

USRCAL,UANBEG

This command is trapped by the Mechanical APDL Launcher so that a Python gRPC server is up and running when the Mechanical APDL process starts.

When launching Mechanical APDL using this input file, you will see the following printout to indicate Mechanical APDL detected the Python UPF instructions and has launched a Python server:

Processing "/upf" found in input file "my_inp.dat"

 Python UPF Detected

PYTHON VERSION : 3.6
>>
>> START PYTHON GRPC SERVER
>>
>> User Functions Python File :  my_upf.py
>>
>> Server started on port [50054]

During the Mechanical APDL process, you will see this Python printout:

RUN SETUP PROCEDURE FROM FILE= /ansys_inc/v242/ansys/apdl/start.ans
 =======================================
 >> Inside the PYTHON UAnBeg routine  <<
 =======================================

At the very end of the process, the Python server is automatically shutdown:

…
|-----------------------------------------------------------------|
|                                                                 |
|   CP Time      (sec) =          0.326       Time  =  10:40:24   |
|   Elapsed Time (sec) =          2.000       Date  =  03/11/2021 |
|                                                                 |
*-----------------------------------------------------------------*

>> We shutdown Python Server(s)