3.2.12. User-Defined Memory (UDM) Macros

This section contains macros that access user-defined memory (UDM) and user-defined node memory (UDNM) variables in ANSYS Fluent.

Before you can store variables in memory using the macros provided below, you will first need to allocate the appropriate number of memory location(s) in the User-Defined Memory dialog box in ANSYS Fluent.

 Parameters & Customization → User Defined Memory  Edit...


Important:  Note that if you try to use F_UDMI, C_UDMI, or N_UDMI before you have allocated memory, then an error will result.


A variable will be created for every user-defined memory and user-defined node memory location that you allocate in the graphical user interface. For example, if you specify 2 as the Number of User-Defined Memory Locations or Number of User-Defined Node Memory Locations, then two variables with default names User Memory 0 and User Memory 1, or User Node Memory 0 and User Node Memory 1 will be defined for your model and the default variable names will appear in postprocessing dialog boxes. You can change the default names if you want, using Set_User_Memory_Name or Set_User_Node_Memory_Name as described below.


Important:  The total number of memory locations is limited to 500. For large numbers of memory locations, system memory requirements will increase.


3.2.12.1. Set_User_Memory_Name

The default name that appears in the graphical user interface and on plots for user-defined memory (UDM) values in ANSYS Fluent (for example, User Memory 0) can be changed using the function Set_User_Memory_Name.

 void Set_User_Memory_Name(int i,char *name); 

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

The Set_User_Memory_Name function should be used only once and it is best used in an EXECUTE_ON_LOADING UDF (see DEFINE_EXECUTE_ON_LOADING ). Due to the mechanism used, User Memory values 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.12.2. Set_User_Node_Memory_Name

The default name that appears in the graphical user interface and on plots for user-defined node memory values in ANSYS Fluent (for example, User Node Memory 0) can be changed using the function Set_User_Node_Memory_Name.

 void Set_User_Node_Memory_Name(int i,char *name); 

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

The Set_User_Node_Memory_Name function should be used only once and is best used in an EXECUTE_ON_LOADING UDF. Due to the mechanism used, User Memory values 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.12.3. F_UDMI

You can use F_UDMI (Table 3.39: Storage of User-Defined Memory on Faces (mem.h)) to access or store the value of the user-defined memory on a face. F_UDMI can be used to allocate up to 500 memory locations in order to store and retrieve the values of face field variables computed by UDFs. These stored values can then be used by other UDFs.


Important:  Note that F_UDMI is available for wall and flow boundary faces, only.


Table 3.39:  Storage of User-Defined Memory on Faces (mem.h)

Macro

Argument Types

Usage

F_UDMI(f,t,i)

face_t f, Thread *t, int i

stores the face value of a user- defined memory with index i


There are three arguments to F_UDMI: f, t, and i. f is the face identifier, t is a pointer to the face thread, and i is an integer index that identifies the memory location where data is to be stored. An index i of 0 corresponds to user-defined memory location 0 (or User Memory 0).

Example

 /* Compute face temperature and store in user-defined memory */
 begin_f_loop(f,t)
  {
    temp = F_T(f,t);
    F_UDMI(f,t,0) = (temp - tmin) / (tmax-tmin);
  }
 end_f_loop(f,t)
 } 

See DEFINE_DPM_EROSION for another example of F_UDMI usage.

3.2.12.4. C_UDMI

You can use C_UDMI to access or store the value of the user-defined memory in a cell. C_UDMI can be used to allocate up to 500 memory locations in order to store and retrieve the values of cell field variables computed by UDFs (Table 3.40: Storage of User-Defined Memory in Cells (mem.h)). These stored values can then be used for postprocessing, for example, or by other UDFs. See Example UDF that Utilizes UDM and UDS Variables for an example of C_UDMI usage.

Table 3.40:  Storage of User-Defined Memory in Cells (mem.h)

Macro

Argument Types

Usage

C_UDMI(c,t,i)

cell_t c, Thread *t, int i

stores the cell value of a user- defined memory with index i


There are three arguments to C_UDMI: c, thread, and i. c is the cell identifier, thread is a pointer to the cell thread, and i is an integer index that identifies the memory location where data is to be stored. An index i of 0 corresponds to user-defined memory location 0 (or User Memory 0).

3.2.12.5. N_UDMI

You can use N_UDMI to access or store the value of the user-defined memory in a mesh node. N_UDMI can be used to allocate up to 500 memory locations (Table 3.41: Storage of User-Defined Memory at Mesh Nodes (mem.h)). These stored values can then be used for postprocessing, for example, or by other UDFs.

Table 3.41:  Storage of User-Defined Memory at Mesh Nodes (mem.h)

Macro

Argument Types

Usage

N_UDMI(v,i)

Node *v, int i

stores the node value of a user- defined memory with index i


There are two arguments to N_UDMI: v, and i. v is a pointer to the mesh node, and i is an integer index that identifies the memory location where data is to be stored. An index i of 0 corresponds to user-defined memory location 0 (or User Node Memory 0).

Example

 /* Store the mesh node coordinates in user-defined node memory */
 thread_loop_c (t,domain)
  {
  begin_c_loop (c,t)
   {
   c_node_loop (c,t,n)
    {
    v = C_NODE(c,t,n);
    N_UDMI(v,0) = NODE_X(v);
    N_UDMI(v,1) = NODE_Y(v);
 #if RP_3D
    N_UDMI(v,2) = NODE_Z(v);
 #endif
    }
   }
  end_c_loop (c,t)
  } 

3.2.12.6. Example UDF that Utilizes UDM and UDS Variables

UDMs are often used to store diagnostic values derived from calculated values of a UDS. Below is an example that shows a technique for plotting the gradient of any flow variable. In this case, the volume fraction of a phase is loaded into a user scalar. If an iteration is made such that the UDS is not calculated, the gradients of the scalar will nevertheless be updated without altering the values of the user scalar. The gradient is then available to be copied into a User Memory variable for displaying.

 # include "udf.h"
 # define domain_ID 2
 
 DEFINE_ADJUST(adjust_gradient, domain)
 {
    Thread *t;
    cell_t c;
    face_t f;
    domain = Get_Domain(domain_ID);
    /* Fill UDS with the variable. */
    thread_loop_c (t,domain)
      {
      begin_c_loop (c,t)
         {
         C_UDSI(c,t,0) = C_VOF(c,t);
         }
      end_c_loop (c,t)
      }
    thread_loop_f (t,domain)
      {
      if (THREAD_STORAGE(t,SV_UDS_I(0))!=NULL)
        begin_f_loop (f,t)
         {
         F_UDSI(f,t,0) = F_VOF(f,t);
         }
      end_f_loop (f,t)
      }
 }
 
 DEFINE_ON_DEMAND(store_gradient)
 {  Domain *domain;
    cell_t c;
    Thread *t;
    domain=Get_Domain(1);
    /* Fill the UDM with magnitude of gradient. */
    thread_loop_c (t,domain)
      {
      begin_c_loop (c,t)
       {
         C_UDMI(c,t,0) = NV_MAG(C_UDSI_G(c,t,0));
       }
      end_c_loop (c,t)
      }
 } 

3.2.12.7. Reserving UDM Variables Using Reserve_User_Memory_Vars

The capability of loading more than one UDF library into ANSYS Fluent raises the possibility of user-defined memory (UDM) clashes. If, for example, you want to use one UDF library that has a fixed 2D magnetic field stored in User Memory 0 and User Memory 1 and you want to use another UDF library that models the mass exchange between phases using User Memory 0 for the exchange rates and these two libraries are loaded at the same time, then the two models are going to interfere with each other’s data in User Memory 0. To avoid data contention problems, ANSYS Fluent has a macro that will allow a UDF library to "reserve" UDM locations prior to usage. Note that there are other methods you can use within UDFs to hardcode the offset for UDMs to prevent contention that are not discussed here.

  int Reserve_User_Memory_Vars(int num)
  

The integer given as an argument to the macro (num) specifies the number of UDMs needed by the library. The integer returned by the function is the starting point or “offset" from which the library may use the UDMs. It should be saved as a global integer such as offset in the UDF and it should be initialized to the special variable UDM_UNRESERVED.

 offset = Reserve_User_Memory_Vars(int num); 

Reserve_User_Memory_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, although this is discouraged except for testing purposes. After a UDM is reserved, it can be set to unique names for the particular library using Set_User_Memory_Name (see below for details.) After the number of UDMs that are needed by a particular library is set in the GUI and the UDMs 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 memory locations without interference. Two example source code files named udm_res1.c and udm_res2.c each containing two UDFs are listed below. The first UDF is an EXECUTE_ON_LOADING UDF that is used to reserve UDMs for the library and set unique names for the UDM locations so that they can be easily identified in postprocessing. The second UDF is an ON_DEMAND UDF that is used to set the values of the UDM locations after the solution has been initialized. The ON_DEMAND UDF sets the initial values of the UDM locations using udf_offset, which is defined in the EXECUTE_ON_LOADING UDF. Note that the on demand UDF must be executed after the solution is initialized to reset the initial values for the UDMs.

The following describes the process of reserving five UDMs for two libraries named libudf and libudf2.

  1. In the User-Defined Memory dialog box, specify 5 for the Number of User-Defined Memory Locations.

  2. In the Compiled UDFs dialog box, build the compiled library named libudf for udm_res1.c and load the library.

  3. Build the compiled library for udm_res2.c named libudf2 and load the library.

  4. Initialize the solution.

  5. Execute the on-demand UDFs for libudf and libudf2 in the Execute On Demand dialog box.

  6. Iterate the solution.

  7. Postprocess the results.

3.2.12.8. Example 1

 /**********************************************************************
   udm_res1.c contains two UDFs: an execute on loading UDF that reserves
   three UDMs for libudf and renames the UDMs to enhance postprocessing,
   and an on-demand UDF that sets the initial value of the UDMs.
 **********************************************************************/
 #include "udf.h"
 
 #define NUM_UDM 3 static int udm_offset = UDM_UNRESERVED;
 
 DEFINE_EXECUTE_ON_LOADING(on_loading, libname)
 {
    if (udm_offset == UDM_UNRESERVED) udm_offset =
      Reserve_User_Memory_Vars(NUM_UDM);
    if (udm_offset == UDM_UNRESERVED)
     Message("\nYou need to define up to %d extra UDMs in GUI and "
        "then reload current library %s\n", NUM_UDM, libname);
    else
     {
      Message("%d UDMs have been reserved by the current "
        "library %s\n", NUM_UDM, libname);
      Set_User_Memory_Name(udm_offset,"lib1-UDM-0");
      Set_User_Memory_Name(udm_offset+1,"lib1-UDM-1");
      Set_User_Memory_Name(udm_offset+2,"lib1-UDM-2");
     }
    Message("\nUDM Offset for Current Loaded Library = %d",udm_offset);
 }
 
 DEFINE_ON_DEMAND(set_udms)
 {
  Domain *d;
  Thread *ct;
  cell_t c;
  int i;  d=Get_Domain(1);
  if(udm_offset != UDM_UNRESERVED)
   {
    Message("Setting UDMs\n");
    for (i=0;i<NUM_UDM;i++)
      {
     thread_loop_c(ct,d)
       {
        begin_c_loop(c,ct)
        {
         C_UDMI(c,ct,udm_offset+i)=3.0+i/10.0;
         }
        end_c_loop(c,ct)
       }
     }
   }
  else
  Message("UDMs have not yet been reserved for library 1\n");
 } 

3.2.12.9. Example 2

 ***********************************************************************/
   udm_res2.c contains two UDFs: an execute on loading UDF that reserves
   two UDMs for libudf and renames the UDMs to enhance postprocessing,
   and an on-demand UDF that sets the initial value of the UDMs.
 **********************************************************************/
 #include "udf.h"
 
 #define NUM_UDM 2 static int udm_offset = UDM_UNRESERVED;
 
 DEFINE_EXECUTE_ON_LOADING(on_loading, libname)
 {
  if (udm_offset == UDM_UNRESERVED) udm_offset =
    Reserve_User_Memory_Vars(NUM_UDM);
  if (udm_offset == UDM_UNRESERVED)
   Message("\nYou need to define up to %d extra UDMs in GUI and "
     "then reload current library %s\n", NUM_UDM, libname);
  else
   {
  Message("%d UDMs have been reserved by the current "
     "library %s\n", NUM_UDM, libname);
  Set_User_Memory_Name(udm_offset,"lib2-UDM-0");
  Set_User_Memory_Name(udm_offset+1,"lib2-UDM-1");
 }
  Message("\nUDM Offset for Current Loaded Library = %d",udm_offset);
 }
 
 DEFINE_ON_DEMAND(set_udms)
 {
  Domain *d;
  Thread *ct;
  cell_t c;
  int i;
 d=Get_Domain(1);
  if(udm_offset != UDM_UNRESERVED)
   {
    Message("Setting UDMs\n");
    for (i=0;i<NUM_UDM;i++)
      {
     thread_loop_c(ct,d)
       {
        begin_c_loop(c,ct)
        {
         C_UDMI(c,ct,udm_offset+i)=2.0+i/10.0;
         }
        end_c_loop(c,ct)
       }
     }
   }
  else
  Message("UDMs have not yet been reserved for library 1\n");
 } 

If your model uses a number of UDMs, it may be useful to define your variables in an easy-to-read format, either at the top of the source file or in a separate header file using the preprocessor #define directive:

  #define C_MAG_X(c,t)C_UDMI(c,t,udm_offset)
  #define C_MAG_Y(c,t)C_UDMI(c,t,udm_offset+1)
  

Following this definition, in the remainder of your UDF you can simply use C_MAG_X(c,t) and C_MAG_Y(c,t) to specify the fixed magnetic field components.

3.2.12.10. Unreserving UDM Variables

ANSYS Fluent does not currently provide the capability to unreserve UDM variables using a macro. Unreserve macros will be available in future versions of ANSYS Fluent. You will need to exit ANSYS Fluent to ensure that all UDM variables are reset.


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