3.2.11. User-Defined Scalar (UDS) Transport Equation Macros

This section contains macros that you can use when defining scalar transport UDFs in ANSYS Fluent. Note that if you try to use the macros listed below (for example, F_UDSI, C_UDSI) before you have specified user-defined scalars in your ANSYS Fluent model (in the User-Defined Scalars dialog box), then an error will result.

3.2.11.1.  Set_User_Scalar_Name

ANSYS Fluent assigns a default name for every user-defined scalar that you allocate in the graphical user-interface. For example, if you specify 2 as the Number of User-Defined Scalars, then two variables with default names User Scalar 0 and User Scalar 1 will be defined and the variables with these default names will appear in setup and postprocessing dialog boxes. You can change the default names if you want, using Set_User_Scalar_Name as described below.

The default name that appears in the graphical user interface and on plots in ANSYS Fluent for user-defined scalars (for example, User Scalar 0) can now be changed using the function Set_User_Scalar_Name.

 void Set_User_Scalar_Name(int i,char *name); 

i is the index of the scalar and name is a string containing the name you want to assign. It is defined in sg_udms.h.

Set_User_Scalar_Name should be used only once and is best used in an EXECUTE_ON_LOADING UDF (see DEFINE_EXECUTE_ON_LOADING ). Due to the mechanism used, UDS variables cannot be renamed after they have been set, so if the name is changed in a UDF, for example, and the UDF library is reloaded, then the old name could remain. In this case, restart ANSYS Fluent and load the library again.

3.2.11.2. F_UDSI

You can use F_UDSI when you want to access face variables that are computed for user-defined scalar transport equations (Table 3.37: Accessing User-Defined Scalar Face Variables (mem.h)). See Example UDF that Utilizes UDM and UDS Variables for an example of F_UDSI usage.

Table 3.37:  Accessing User-Defined Scalar Face Variables (mem.h)

Macro

Argument Types

Returns

F_UDSI(f,t,i)

face_t f, Thread *t, int i

Note: i is index of scalar

UDS face variables



Important:  Note that F_UDSI is available for wall and flow boundary faces, only. If a UDS attempts to access any other face zone, then an error will result.


3.2.11.3. C_UDSI

You can use C_UDSI when you want to access cell variables that are computed for user-defined scalar transport equations. Macros for accessing UDS cell variables are listed in Table 3.38: C_UDSI for Accessing UDS Transport Cell Variables (mem.h). Some examples of usage for these macros include defining non-constant source terms for UDS transport equations and initializing equations. See Example UDF that Utilizes UDM and UDS Variables for an example of C_UDSI usage.

Table 3.38:  C_UDSI for Accessing UDS Transport Cell Variables (mem.h)

Macro

Argument Types

Returns

C_UDSI(c,t,i)

cell_t c, Thread *t, int i

UDS cell variables

C_UDSI_G(c,t,i)

cell_t c, Thread *t, int i

UDS gradient

C_UDSI_M1(c,t,i)

cell_t c, Thread *t, int i

UDS previous time step

C_UDSI_M2(c,t,i)

cell_t c, Thread *t, int i

UDS second previous time step

C_UDSI_DIFF(c,t,i)

cell_t c, Thread *t, int i

Note: i is index of scalar

UDS diffusivity


3.2.11.4. Reserving UDS Variables

Prior to use, you can reserve scalar variables to avoid data conflicts between multiple UDF libraries using the same user-defined scalars (see Reserve_User_Scalar_Vars ).

3.2.11.5. Reserve_User_Scalar_Vars

The new capability of loading more than one UDF library into ANSYS Fluent raises the possibility of user-defined scalar (UDS) clashes. To avoid data contention between multiple UDF libraries using the same user-defined scalars, ANSYS Fluent has provided the macro Reserve_User_Scalar_Vars that allows you to reserve scalars prior to use.

 int Reserve_User_Scalar_Vars(int num) 

int num is the number of user-defined scalars that the library uses. The integer returned is the lowest UDS index that the library may use. After calling:

 offset = Reserve_User_Scalar_Vars(int num); 

the library may safely use C_UDSI(c,t,offset) to C_UDSI(c,t,offset+num-1). See DEFINE_EXECUTE_ON_LOADING for an example of macro usage. Note that there are other methods you can use within UDFs to hardcode the offset to prevent data contention.

Reserve_User_Scalar_Vars (defined in sg_udms.h) is designed to be called from an EXECUTE_ON_LOADING UDF ( DEFINE_EXECUTE_ON_LOADING ). An on-loading UDF, as its name implies, executes as soon as the shared library is loaded into ANSYS Fluent. The macro can also be called from an INIT or ON_DEMAND UDF. After a user scalar has been reserved, it can be set to unique names for the particular library using Set_User_Memory_Name (see below for details on Set_User_Memory_Name). After the number of UDS that are needed by a particular library is set in the GUI and the variables are successfully reserved for the loaded library, the other functions in the library can safely use C_UDMI(c,t,offset) up to C_UDMI(c,t,offset+num-1) to store values in user scalars without interference.

3.2.11.6. Unreserving UDS Variables

ANSYS Fluent does not currently provide the capability to unreserve UDS variables using a macro. Unreserve macros will be available in future versions of ANSYS Fluent.

3.2.11.7. N_UDS

You can use N_UDS to access the number of user-defined scalar (UDS) transport equations that have been specified in ANSYS Fluent. The macro takes no arguments and returns the integer number of equations. It is defined in models.h.


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