19.1.1. Structure of User CEL Functions

A User Fortran file may contain several user routines that can be called from the CFX-Solver, as well as any secondary routines that are called only from other routines in this file.

In addition to any comments and declarations that you may want to add, the basic structure of a user CEL function is:

#include "cfx5ext.h"
dllexport(<callingname>)
      SUBROUTINE <callingname>(
      &  NLOC, NRET, NARG, RET, ARGS, CRESLT, CZ,DZ,IZ,LZ,RZ )
C
      INTEGER NLOC,NARG,NRET
      CHARACTER CRESLT*(*)
      REAL ARGS(NLOC,NARG), RET(NLOC,NRET)
C
      INTEGER IZ(*)
      CHARACTER CZ(*)*(1)
      DOUBLE PRECISION DZ(*)
      LOGICAL LZ(*)
      REAL RZ(*)
C
      .... executable statements
      END

The dllexport() macro is used to ensure that a calling name is known externally on those platforms that require it for successful run-time linking. The macro is defined in an include file so #include "cfx5ext.h" should be the first line of the Fortran file.

One dllexport() should be specified for every routine that the CFX-Solver can call in the Fortran file, and each dllexport() macro must precede the SUBROUTINE statement that it refers to and must start in column 1. The argument of the dllexport macro should be the name of the subroutine in lower case and should not contain spaces.

User CEL functions have a fixed argument list that contains the following data fields:

  • NLOC: Number of locations in space over which the calculations have to be performed.

  • NARG: Number of arguments passed to the function.

  • ARGS(1:NLOC,1:NARG): Arguments passed to the function (at each point in space).

  • NRET: Number of return variables. This is always 1 in CFX, but is included to enable future extensions.

  • RET(1:NLOC,1:NRET): Return variables (at each point in space).

  • CZ(*), DZ(*), IZ(*), LZ(*), RZ(*): CHARACTER, DOUBLE PRECISION, INTEGER, LOGICAL and REAL stacks.

The length (NLOC) of the arguments (ARGS) and the return value (RET) of user CEL functions is determined by the locale for which the routine is called. For example, for a boundary element group, NLOC is the number of faces in the group, and for vertices, NLOC is the number of vertices in the current zone.

Note that, in general, your user CEL function will be called several times during each iteration and the value of NLOC will be different for each call. This is because the CFX-Solver will split the specified region (for example, a boundary condition region) into a number of smaller ‘pieces’ and call your function for each piece. Your user subroutine should be coded to deal with this.

The stacks are required if the information specified on the right side of the CEL expression (for example, B*C and D in A = UR(B*C, D)) is not sufficient to calculate A. It might be necessary to pick up additional data (such as user input data, data at other locales, gradients, and so on). For details, see Utility Routines for User Functions. This data is accessed from the CFX Memory Management System and requires the global stacks; therefore, the global stacks are added to the argument list. For details, see CFX Memory Management System (MMS).

A template user CEL function Fortran file named ucf_template.F can be found in <CFXROOT>/examples/.

Note that all strings used in User Fortran are case-sensitive.