The macro F_NNODES shown in Table 3.2: Macro for Number of Nodes Defined in mem.h returns the integer number of nodes associated with a face.

The macro listed in Table 3.3: Macro for Cell Centroids Defined in metric.h can be used to obtain the real centroid of a cell. C_CENTROID finds the coordinate position of the centroid of the cell c and stores the coordinates in the x array. Note that the x array is always one-dimensional, but it can be x[2] or x[3] depending on whether you are using the 2D or 3D solver.

See DEFINE_INIT for an example UDF that utilizes C_CENTROID.

The macro listed in Table 3.4: Macro for Cell Volume Defined in mem.h can be used to obtain the real cell volume for 2D, 3D, and axisymmetric simulations.

See DEFINE_UDS_UNSTEADY C_VOLUME.

The macro C_NFACES shown in Table 3.5: Macros for Number of Node and Faces Defined in mem.h returns the integer number of faces for a given cell. C_NNODES, also shown in Table 3.2: Macro for Number of Nodes Defined in mem.h , returns the integer number of nodes for a given cell.

C_FACE expands to return the global face index face_t f for the given cell_t c, Thread *t, and local face index number i. Specific faces can be accessed via the integer index i and all faces can be looped over with c_face_loop. The macro is defined in mem.h.

C_FACE_THREAD expands to return the Thread *t of the face_t f that is returned by C_FACE (see above). Specific faces can be accessed via the integer index i and all faces can be looped over with c_face_loop. The macro is defined in mem.h.

You can access flow variables using macros listed in Table 3.8: Macros for Cell Flow Variables Defined in mem.h or sg_mem.h.

You can access gradient and reconstruction gradient vectors (and components) for many of the cell variables listed in Table 3.8: Macros for Cell Flow Variables Defined in mem.h or sg_mem.h. Ansys Fluent calculates the gradient of flow in a cell (based on the divergence theory) and stores this value in the variable identified by the suffix _G. For example, cell temperature is stored in the variable C_T, and the temperature gradient of the cell is stored in C_T_G. The gradients stored in variables with the _G suffix are non-limited values and if used to reconstruct values within the cell (at faces, for example), may potentially result in values that are higher (or lower) than values in the surrounding cells. Therefore, if your UDF needs to compute face values from cell gradients, you should use the reconstruction gradient (RG) values instead of non-limited gradient (G) values. Reconstruction gradient variables are identified by the suffix _RG, and use the limiting method that you have activated in your Ansys Fluent model to limit the cell gradient values.

Gradient (G) Vector Macros

Table 3.10: Macros for Cell Gradients Defined in mem.h shows a list of cell gradient vector macros. Note that gradient variables are available only when the equation for that variable is being solved. For example, if you are defining a source term for energy, your UDF can access the cell temperature gradient (using C_T_G), but it cannot get access to the x-velocity gradient (using C_U_G). The reason for this is that the solver continually removes data from memory that it does not need. In order to retain the gradient data (when you want to set up user-defined scalar transport equations, for example), you can prevent the solver from freeing up memory by enabling the following text command: solve/set/advanced/retain-temporary-solver-mem. Note that when you do this, all of the gradient data is retained, but the calculation requires more memory to run.

You can access a component of a gradient vector by specifying it as an argument in the gradient vector call (0 for the x component; 1 for y; and 2 for z). For example,

C_T_G(c,t)[0]; /* returns the x-component of the cell temperature gradient vector */ 

As stated previously, the availability of gradient variables is affected by your solver selection, which models are turned on, the setting for the spatial discretization, and whether the temporary solver memory is retained. To make it easy for you to verify what gradient variables are available for your particular case and data files, the following UDF (named showgrad.c) is provided. Simply compile this UDF, run your solution, and then hook the UDF using the Execute on Demand dialog box (as described in Hooking DEFINE_ON_DEMAND UDFs). The available gradient variables will be displayed in the console.

 /*
 * ON Demand User-Defined Functions to check                              *
 * on the availability of Reconstruction Gradient and Gradients           *
 * for a given Solver and Solver settings:                                *
 *                                                                        *
 * Availability of Gradients & Reconstruction Gradients depends on:       *
 * 1) the selected Solver (density based or pressure based)               *
 * 2) the selected Model                                                  *
 * 3) the order of discretizations                                        *
 * 4) whether the temporary solver memory is being retained (to keep      *
 *    temporary memory, enable the following text command:                *
 *    solve/set/advanced/retain-temporary-solver-mem.                     *
 *                                                                        *
 *                                                                        *
 * How to use showgrad:                                                   *
 *                                                                        *
 * - Read in your case & data file.                                       *
 * - Compile showgrad.c UDF.                                              *
 * - Load library libudf.                                                 *
 * - Attach the showgrad UDF in the Execute on Demand dialog box.         *
 * - Run your solution.                                                   *
 * - Click the Execute button in the Execute on Demand dialog box.        *
 *                                                                        *
 * A list of available Grads and Recon Grads will be displayed in the     *
 * console.                                                               *
 *                                                                        *
 * 2004 Laith Zori                                                        *
 */ #include "udf.h"
 
 DEFINE_ON_DEMAND(showgrad)
 {
    Domain *domain;
    Thread *t;  domain=Get_Domain(1);
    if (! Data_Valid_P()) return;
    Message0(" >>> entering show-grad: \n ");
    thread_loop_c(t, domain)
      {
       Material *m = THREAD_MATERIAL(t);
       int nspe = MIXTURE_NSPECIES(m);
       int nspm = nspe-1;
       Message0("::::\n ");
       Message0("::::  Reconstruction Gradients :::: \n ");
       Message0("::::\n ");
       if (NNULLP(THREAD_STORAGE(t, SV_P_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of P is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_U_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of U is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_V_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of V is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_W_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of W is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_T_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of T is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_H_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of H is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_K_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of K is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_D_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of D is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_O_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of O is available \n ");
         }
       if (NNULLP(THREAD_STORAGE(t, SV_NUT_RG)))
         {
          Message0("....show-grad:Reconstruction Gradient of NUT is available \n ");
         }
 
       if (nspe && NNULLP(THREAD_STORAGE(t, SV_Y_RG)))
         {
           Message0("....show-grad:Reconstruction Gradient of Species is available \n ");
         }
 
     /********************************************************************/
     /********************************************************************/
     /********************************************************************/
     /********************************************************************/
     Message0("::::\n ");
     Message0("::::   Gradients :::: \n ");
     Message0("::::\n ");
     if (NNULLP(THREAD_STORAGE(t, SV_P_G)))
        {
         Message0("....show-grad:Gradient of P is available \n ");
        }
     if (NNULLP(THREAD_STORAGE(t, SV_U_G)))
        {
         Message0("....show-grad:Gradient of U is available \n ");
        }
     if (NNULLP(THREAD_STORAGE(t, SV_V_G)))
       {
        Message0("....show-grad:Gradient of V is available \n ");
       }
    if (NNULLP(THREAD_STORAGE(t, SV_W_G)))
       {
        Message0("....show-grad:Gradient of W is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_T_G)))
       {
        Message0("....show-grad:Gradient of T is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_H_G)))
       {
        Message0("....show-grad:Gradient of H is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_K_G)))
       {
        Message0("....show-grad:Gradient of K is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_D_G)))
       {
        Message0("....show-grad:Gradient of D is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_O_G)))
       {
        Message0("....show-grad:Gradient of O is available \n ");
       }
     if (NNULLP(THREAD_STORAGE(t, SV_NUT_G)))
       {
        Message0("....show-grad:Gradient of NUT is available \n ");
       }
 
     if (nspe && NNULLP(THREAD_STORAGE(t, SV_Y_G)))
         {
           Message0("....show-grad:Gradient of Species is available \n ");
         }
    }
 } 

Reconstruction Gradient (RG) Vector Macros

Table 3.11: Macros for Cell Reconstruction Gradients (RG) Defined in mem.h shows a list of cell reconstruction gradient vector macros. Like gradient variables, RG variables are available only when the equation for that variable is being solved. As in the case of gradient variables, you can retain all of the reconstruction gradient data by enabling the following text command: solve/set/advanced/retain-temporary-solver-mem. Note that when you do this, the reconstruction gradient data is retained, but the calculation requires more memory to run.

You can access a component of a reconstruction gradient vector by specifying it as an argument in the reconstruction gradient vector call (0 for the x component; 1 for y; and 2 for z). For example,

 C_T_RG(c,t)[0]; /* returns the x-component of the cell temperature
                    reconstruction gradient vector */ 

As stated previously, the availability of reconstruction gradient variables is affected by your solver selection, which models are turned on, the setting for the spatial discretization, and whether the temporary solver memory is freed. To make it easy for you to verify which reconstruction gradient variables are available for your particular case and data files, a UDF (named showgrad.c) has been provided that will display the available gradients in the console. See the previous section for details.

The _M1 suffix can be applied to some of the cell variable macros in Table 3.8: Macros for Cell Flow Variables Defined in mem.h or sg_mem.h to allow access to the value of the variable at the previous time step (that is, ). These data may be useful in unsteady simulations. For example,

 C_T_M1(c,t); 

returns the value of the cell temperature at the previous time step. Previous time step macros are shown in Table 3.12: Macros for Cell Time Level 1 Defined in mem.h .

See DEFINE_UDS_UNSTEADY for an example UDF that utilizes C_R_M1.

The M2 suffix can be applied to some of the cell variable macros in Table 3.12: Macros for Cell Time Level 1 Defined in mem.h to allow access to the value of the variable at the time step before the previous one (that is, ). These data may be useful in unsteady simulations. For example,

 C_T_M2(c,t); 

returns the value of the cell temperature at the time step before the previous one (referred to as second previous time step). Two previous time step macros are shown in Table 3.13: Macros for Cell Time Level 2 Defined in mem.h .

The macros listed in Table 3.14: Macros for Cell Velocity Derivatives Defined in mem.h can be used to return real velocity derivative variables in SI units. The variables are available in both the pressure-based and the density-based solvers. Definitions for these macros can be found in the mem.h header file.

The macros listed in Table 3.15: Macros for Diffusion Coefficients Defined in mem.h – Table 3.17: Additional Material Property Macros Defined in sg_mem.h can be used to return real material property variables in SI units. The variables are available in both the pressure-based and the density-based solvers. Argument real prt is the turbulent Prandtl number. Definitions for material property macros can be found in the referenced header file (for example, mem.h).

The macros listed in Table 3.19: Macros for Reynolds Stress Model Variables Defined in sg_mem.h can be used to return real variables for the Reynolds stress turbulence model in SI units. The variables are available in both the pressure-based and the density-based solvers. Definitions for these macros can be found in the metric.h header file.

The macros listed in Table 3.20: Macros for Multiphase Variables Defined in sg_mphase.h can be used to return real variables associated with the multiphase models in SI units. The variables are available only in the pressure-based solver. Definitions for these macros can be found in sg_mphase.h, which is included in udf.h.

The macros listed in Table 3.21: Macros for Potential/Electrochemistry Model Variables Defined in mem.h can be used to return real variables associated with the potential model in SI units. The variables are available only in the pressure-based solver. Definitions for these macros can be found in mem.h, which is included in udf.h.

The macro listed in Table 3.22: Macro for Face Centroids Defined in metric.h can be used to obtain the real centroid of a face. F_CENTROID finds the coordinate position of the centroid of the face f and stores the coordinates in the x array. Note that the x array is always one-dimensional, but it can be x[2] or x[3] depending on whether you are using the 2D or 3D solver.

The ND_ND macro returns 2 or 3 in 2D and 3D cases, respectively, as defined in The ND Macros. DEFINE_PROFILE contains an example of F_CENTROID usage.

F_AREA can be used to return the real face area vector (or ‘face area normal’) of a given face f in a face thread t. See DEFINE_UDS_FLUX for an example UDF that utilizes F_AREA.

By convention in Ansys Fluent, boundary face area normals always point out of the domain. Ansys Fluent determines the direction of the face area normals for interior faces by applying the right hand rule to the nodes on a face, in order of increasing node number. This is shown in Figure 3.1: Ansys Fluent Determination of Face Area Normal Direction: 2D Face.

Figure 3.1: Ansys Fluent Determination of Face Area Normal Direction: 2D Face

Ansys Fluent assigns adjacent cells to an interior face (c0 and c1) according to the following convention: the cell out of which a face area normal is pointing is designated as cell C0, while the cell in to which a face area normal is pointing is cell c1 (Figure 3.1: Ansys Fluent Determination of Face Area Normal Direction: 2D Face). In other words, face area normals always point from cell c0 to cell c1.

The macros listed in Table 3.24: Macros for Boundary Face Flow Variables Defined in mem.h access flow variables at a boundary face.

See DEFINE_UDS_FLUX for an example UDF that utilizes some of these macros.

The macros listed in Table 3.25: Macros for Interior and Boundary Face Flow Variables Defined in mem.h access flow variables at interior faces and boundary faces.

F_FLUX can be used to return the real scalar mass flow rate through a given face f in a face thread t. The sign of F_FLUX that is computed by the Ansys Fluent solver is positive if the flow direction is the same as the face area normal direction (as determined by F_AREA - see Face Area Vector (F_AREA)), and is negative if the flow direction and the face area normal directions are opposite. In other words, the flux is positive if the flow is out of the domain, and is negative if the flow is in to the domain.

Note that the sign of the flux that is computed by the solver is opposite to that which is reported in the Ansys Fluent GUI (for example, the Flux Reports dialog box).

The cells on either side of a face may or may not belong to the same cell thread. Referring to Figure 3.2: Adjacent Cells c0 and c1 with Vector and Gradient Definitions, if a face is on the boundary of a domain, then only c0 exists. (c1 is undefined for an external face). Alternatively, if the face is in the interior of the domain, then both c0 and c1 exist.

There are two macros, F_C0(f,t) and F_C1(f,t), that can be used to identify cells that are adjacent to a given face thread t. F_C0 expands to a function that returns the index of a face’s neighboring c0 cell (Figure 3.2: Adjacent Cells c0 and c1 with Vector and Gradient Definitions), while F_C1 returns the cell index for c1 (Figure 3.2: Adjacent Cells c0 and c1 with Vector and Gradient Definitions), if it exists.

See DEFINE_UDS_FLUX for an example UDF that utilizes F_C0.

The cells on either side of a face may or may not belong to the same cell thread. Referring to Figure 3.2: Adjacent Cells c0 and c1 with Vector and Gradient Definitions, if a face is on the boundary of a domain, then only c0 exists. (c1 is undefined for an external face). Alternatively, if the face is in the interior of the domain, then both c0 and c1 exist.

There are two macros, THREAD_T0(t) and THREAD_T1(t), that can be used to identify cell threads that are adjacent to a given face f in a face thread t. THREAD_T0 expands to a function that returns the cell thread of a given face’s adjacent cell c0, and THREAD_T1 returns the cell thread for c1 (if it exists).

INTERIOR_FACE_GEOMETRY(f,t,A,ds,es,A_by_es,dr0,dr1) expands to a function that outputs the following variables to the solver, for a given face f, on face thread t. The macro is defined in the sg.h header file which is not included in udf.h. You will need to include this file in your UDF using the #include directive.

Note that INTERIOR_FACE_GEOMETRY can be called to retrieve some of the terms needed to evaluate Equation 3–1 and Equation 3–3.

BOUNDARY_FACE_GEOMETRY(f,t,A,ds,es,A_by_es,dr0) expands to a function that outputs the following variables to the solver, for a given face f, on face thread t. It is defined in the sg.h header file which is not included in udf.h. You will need to include this file in your UDF using the #include directive.

BOUNDARY_FACE_GEOMETRY can be called to retrieve some of the terms needed to evaluate Equation 3–1 and Equation 3–3.

BOUNDARY_FACE_THREAD_P(t) expands to a function that returns TRUE if Thread *t is a boundary face thread. The macro is defined in threads.h which is included in udf.h. See DEFINE_UDS_FLUX for an example UDF that utilizes BOUNDARY_FACE_THREAD_P.

BOUNDARY_SECONDARY_GRADIENT_SOURCE(source,n,dphi,dx,A_by_es,k) expands to a function that outputs the following variables to the solver, for a given face and face thread. It is defined in the sg.h header file which is not included in udf.h. You will need to include this file in your UDF using the #include directive.

BOUNDARY_SECONDARY_GRADIENT_SOURCE can be called to retrieve some of the terms needed to evaluate Equation 3–3.

You can use Lookup_Thread when you want to retrieve the pointer t to the thread that is associated with a given integer zone ID number for a boundary zone. The zone_ID that is passed to the macro is the zone number that Ansys Fluent assigns to the boundary and displays in the boundary condition dialog box (for example, Fluid). Note that this macro does the inverse of THREAD_ID (see below).

There are two arguments to Lookup_Thread. domain is passed by Ansys Fluent and is the pointer to the domain structure. You supply the integer value of zone_ID.

For example, the code

 int zone_ID = 2;
 Thread *thread_name = Lookup_Thread(domain,zone_ID); 

passes a zone ID of to Lookup_Thread. A zone ID of may, for example, correspond to a wall zone in your case.

Now suppose that your UDF needs to operate on a particular thread in a domain (instead of looping over all threads), and the DEFINE macro you are using to define your UDF does not have the thread pointer passed to it from the solver (for example, DEFINE_ADJUST). You can use Lookup_Thread in your UDF to get the desired thread pointer. This is a two-step process.

First, you will need to get the integer ID of the zone by visiting the boundary condition dialog box (for example, Fluid) and noting the zone ID. You can also obtain the value of the Zone ID from the solver using RP_Get_Integer. Note that in order to use RP_Get_Integer, you will have to define the zone ID variable first on the Scheme side using rp-var-define or make-new-rpvar (see Scheme Macros for details.)

Next, you supply the zone_ID as an argument to Lookup_Thread either as a hard-coded integer (for example, 1, 2) or as the variable assigned from RP_Get_Integer. Lookup_Thread returns the pointer to the thread that is associated with the given zone ID. You can then assign the thread pointer to a thread_name and use it in your UDF.

Example

Below is a UDF that uses Lookup_Thread. In this example, the pointer to the thread for a given zone_ID is retrieved by Lookup_Thread and is assigned to thread. The thread pointer is then used in begin_f_loop to loop over all faces in the given thread, and in F_CENTROID to get the face centroid value.

/*******************************************************************
    Example of an adjust UDF that uses Lookup_Thread.
    Note that if this UDF is applied to a multiphase flow problem,
    the thread that is returned is the mixture-level thread
 ********************************************************************/
 
 #include "udf.h"
 
 /* domain passed to Adjust function is mixture domain for multiphase*/
 
 DEFINE_ADJUST(print_f_centroids, domain)
 {
    real FC[2];
    face_t f;
    int ID = 1;
    /* Zone ID for wall-1 zone from Boundary Conditions task page */
    Thread *thread = Lookup_Thread(domain, ID);
    begin_f_loop(f, thread)
    {
       F_CENTROID(FC,f,thread);
       printf("x-coord = %f y-coord = %f", FC[0], FC[1]);
    }
    end_f_loop(f,thread)
 } 

You can use THREAD_ID when you want to retrieve the integer zone ID number (displayed in a boundary conditions dialog box such as Fluid) that is associated with a given thread pointer t. Note that this macro does the inverse of Lookup_Thread (see above).

 int zone_ID = THREAD_ID(t); 

You can use the Get_Domain macro to retrieve a domain pointer when it is not explicitly passed as an argument to your UDF. This is commonly used in ON_DEMAND functions since DEFINE_ON_DEMAND is not passed any arguments from the Ansys Fluent solver. It is also used in initialization and adjust functions for multiphase applications where a phase domain pointer is needed but only a mixture pointer is passed.

 Get_Domain(domain_id); 

domain_id is an integer whose value is 1 for the mixture domain, but the values for the phase domains can be any integer greater than 1. The ID for a particular phase can be found be selecting it in the Phases dialog box in Ansys Fluent.

 Setup → Models → Multiphase → Phases  Edit...

Single-Phase Flows

In the case of single-phase flows, domain_id is 1 and Get_Domain(1) will return the fluid domain pointer.

 DEFINE_ON_DEMAND(my_udf)
 {
    Domain *domain;          /* domain is declared as a variable  */
    domain = Get_Domain(1);  /* returns fluid domain pointer      */
    ...
 } 

Multiphase Flows

In the case of multiphase flows, the value returned by Get_Domain is either the mixture-level, a phase-level, or an interaction phase-level domain pointer. The value of domain_id is always 1 for the mixture domain. You can obtain the domain_id using the Ansys Fluent graphical user interface much in the same way that you can determine the zone ID from the Boundary Conditions task page. Simply go to the Phases dialog box in Ansys Fluent and select the desired phase. The domain_id will then be displayed. You will need to hard code this integer ID as an argument to the macro as shown below.

 DEFINE_ON_DEMAND(my_udf)
 {
    Domain *mixture_domain;
    mixture_domain = Get_Domain(1); /* returns mixture domain pointer */
                                    /* and assigns to variable        */
    Domain *subdomain;
    subdomain = Get_Domain(2);      /* returns phase with ID=2 domain pointer*/
                                    /* and assigns to variable               */
    ...
 } 

Example

The following example is a UDF named get_coords that prints the thread face centroids for two specified thread IDs. The function implements the Get_Domain utility for a single-phase application. In this example, the function Print_Thread_Face_Centroids uses the Lookup_Thread function to determine the pointer to a thread, and then writes the face centroids of all the faces in a specified thread to a file. The Get_Domain(1) function call returns the pointer to the domain (or mixture domain, in the case of a multiphase application). This argument is not passed to DEFINE_ON_DEMAND.

/*****************************************************************
    Example of UDF for single phase that uses Get_Domain utility
 ******************************************************************/
 
 #include "udf.h"
 
 FILE *fout;
 
 void Print_Thread_Face_Centroids(Domain *domain, int id)
 {
    real FC[3];
    face_t f;
    Thread *t = Lookup_Thread(domain, id);
    fprintf(fout,"thread id %d\n", id);
    begin_f_loop(f,t)
      {
      F_CENTROID(FC,f,t);
      fprintf(fout, "f%d %g %g %g\n", f, FC[0], FC[1], FC[2]);
      }
    end_f_loop(f,t)
    fprintf(fout, "\n");
 }
 
 DEFINE_ON_DEMAND(get_coords)
 {
    Domain *domain;
    domain = Get_Domain(1);
    fout = fopen("faces.out", "w");
    Print_Thread_Face_Centroids(domain, 2);
    Print_Thread_Face_Centroids(domain, 4);
    fclose(fout);
 } 

Note that Get_Domain(1) replaces the extern Domain *domain expression used in releases of Ansys Fluent 6.

F_PROFILE is typically used in a DEFINE_PROFILE UDF to set a boundary condition value in memory for a given face and thread. The index i that is an argument to F_PROFILE is also an argument to DEFINE_PROFILE and identifies the particular boundary variable (for example, pressure, temperature, velocity) that is to be set. F_PROFILE is defined in mem.h.

The arguments of F_PROFILE are f, the index of the face face_t; t, a pointer to the face’s thread t; and i, an integer index to the particular face variable that is to be set. i is defined by Ansys Fluent when you hook a DEFINE_PROFILE UDF to a particular variable (for example, pressure, temperature, velocity) in a boundary condition dialog box. This index is passed to your UDF by the Ansys Fluent solver so that the function knows which variable to operate on.

Suppose you want to define a custom inlet boundary pressure profile for your Ansys Fluent case defined by the following equation:

You can set the pressure profile using a DEFINE_PROFILE UDF. Since a profile is an array of data, your UDF will need to create the pressure array by looping over all faces in the boundary zone, and for each face, set the pressure value using F_PROFILE. In the sample UDF source code shown below, the coordinate of the centroid is obtained using F_CENTROID, and this value is used in the pressure calculation that is stored for each face. The solver passes the UDF the right index to the pressure variable because the UDF is hooked to Gauge Total Pressure in the Pressure Inlet boundary condition dialog box. See DEFINE_PROFILE for more information on DEFINE_PROFILE UDFs.

 /***********************************************************************
   UDF for specifying a parabolic pressure profile boundary profile
 ************************************************************************/
 
 #include "udf.h"
 
 DEFINE_PROFILE(pressure_profile,t,i)
 {
    real x[ND_ND];    /* this will hold the position vector */
    real y;
    face_t f;
    begin_f_loop(f,t)
    {
     F_CENTROID(x,f,t);
     y = x[1];
     F_PROFILE(f,t,i) = 1.1e5 - y*y/(.0745*.0745)*0.1e5;
    }
    end_f_loop(f,t)
 } 

THREAD_SHADOW returns the face thread that is the shadow of Thread *t if it is one of a face/face-shadow pair that makes up a thin wall. It returns NULL if the boundary is not part of a thin wall and is often used in an if statement such as:

 if (!NULLP(ts = THREAD_SHADOW(t)))
 {
    /* Do things here using the shadow wall thread (ts) */
 } 

The macros listed in Table 3.28: Macros for Particles at Current Position Defined in dpm_types.h – Table 3.33: Macros for Particle Material Properties Defined in dpm_laws.h can be used to return real variables associated with the Discrete Phase Model (DPM), in SI units (where relevant). They are typically used in DPM UDFs that are described in Discrete Phase Model (DPM) DEFINE Macros. The variables are available in both the pressure-based and the density-based solvers. The macros are defined in the dpm_types.h and dpm_laws.h header files, which are included in udf.h.

The variable tp indicates a pointer to the Tracked_Particle structure (Tracked_Particle *tp) which gives you the value for the particle at the current position, the variable m indicates a pointer to the relevant Material structure (Material *m), and the real variable t is the temperature.

Refer to the following sections for examples of UDFs that use some of these macros: DEFINE_DPM_LAW , DEFINE_DPM_BC , DEFINE_DPM_INJECTION_INIT , DEFINE_DPM_SWITCH , and DEFINE_DPM_PROPERTY .

The TP_... macros listed in Table 3.28: Macros for Particles at Current Position Defined in dpm_types.h through Table 3.32: Macros for Particle Species, Laws, Materials, and User Scalars Defined in dpm_types.h are to be used to access elements of variables of the type Tracked_Particles or elements within instances of the data structure pointed to by pointer variables of the type Tracked_Particle *.

In addition, the dpm_types.h header file also contains definitions for the PP_... macros that are analogous to the corresponding TP_... macros. The PP_... macros are similar in function, but they are to be used for accessing elements of variables of the Particle or elements within the data structure that are pointed to by pointer variables of the type Particle *.

TP_FLOW_RATE(tp)

Each particle in a steady flow calculation represents a "stream" of many particles that follow the same path. The number of particles in this stream that passes a particular point in a second is the "strength" of the stream. TP_FLOW_RATE(tp) returns the strength multiplied by TP_INIT_MASS(tp) at the current particle position.

The following macros can be used in NOx model UDFs in the calculation of pollutant rates. These macros are defined in the header file sg_nox.h, which is included in udf.h. They can be used to return real NOx variables in SI units, and are available in both the pressure-based and the density-based solvers. See DEFINE_NOX_RATE for examples of DEFINE_NOX_RATE UDFs that use these macros.

The macros listed in Table 3.36: Macros for Dynamic Mesh Variables Defined in dynamesh_tools.h are useful in dynamic mesh UDFs. The argument dt is a pointer to the dynamic thread structure, and time is a real value. These macros are defined in the dynamesh_tools.h.

See DEFINE_GRID_MOTION for an example UDF that utilizes DT_THREAD.

The macros listed in Table 3.37: Macros for Battery UDFs Defined in sg_mem.h can be used in a UDF to access the MSMD battery model variables. These macros are defined in the header file sg_mem.h, which is included in udf.h. They can be used to return real variables in SI units. Note that they are available only if the MSMD solution method is used in a simulation.

When using a single-species NIST real gas model, Fluent provides a function that you can use in your UDFs to obtain saturation properties for the bubble and dew points. You can specify either temperature or pressure and the function will return an array containing the pressures or temperatures, respectively, and the liquid and vapor phase densities.

void getsatvalues_NIST(int index, double x, double y[]);

The values returned in y[] depend on the choice of index.

This function can be used regardless of whether you have enabled the lookup table.

int getsatvalues_NIST_msp (int index, double x, double y[], int ibubbleordew)

This function is similar to the single-species function, getsatvalues_NIST, but it applies to multi-species. For a given temperature or pressure you can obtain the corresponding pressure or temperature and the liquid and vapor phase densities.

In the function, index, x, and ibubbleordew are inputs. If the index=0, the input for x is temperature and if the index=1, the input for x is pressure. If ibubbleordew=0, Fluent returns bubble point properties, otherwise it returns dew point properties. y[] is an array of saturation properties.

The function returns an integer indicating the number of interpolation points for a given temperature and pressure:

When index = 0:

When index = 1:

void get_satprop_NIST_msp (index, z, minrho, maxrho, nsat, npts, p_bub, t_bub, p_dew, t_dew);

The 2^nd function for multi-species can be used to generate a saturation table for variable compositions.

Inputs:

Outputs:

This function computes saturation data for the given composition in z. This could be a binary mixture, three species, or more.

#include "udf.h"
#include <string.h>

#define NUM_SAT 50
#define SMALL_NUM 1.e-6
DEFINE_ON_DEMAND(getsat_msp)
{
  double t, p, y[10];
  int np,index;
  int nsat,npts[2];
  double z[10]={0.}, minrho, maxrho;
  double p_bub[NUM_SAT],t_bub[NUM_SAT],p_dew[NUM_SAT],t_dew[NUM_SAT];
  FILE *fp1, *fp2;
  int i,j,k,ncomps=2;

  fp1 = fopen("NIST_Bub_Pnts_Curve.xy", "w");
  fp2 = fopen("NIST_Dew_Pnts_Curve.xy", "w");

  /* test on udf built NIST table - sat */
  minrho = 0.1;
  maxrho = 25.;
  nsat = NUM_SAT;
  z[0] = 0.;
  
  fprintf(fp1, "(title \"Sat Bubble P-T\")");
  fprintf(fp1, "\n(labels \"Temperature (K)\" \"Pressure (kPa)\")\n");
  fprintf(fp2, "(title \"Sat Dew P-T\")");
  fprintf(fp2, "\n(labels \"Temperature (K)\" \"Pressure (kPa)\")\n");
  
  for (j=0; j<21; j++)
 {
    if (z[0] > 1.) z[0] = 1.;
    z[1] = 1. - z[0];
    if (z[1] < 0.) z[1] = 0.;
    get_satprop_NIST_msp(0,z,minrho,maxrho,nsat,npts,p_bub,t_bub,p_dew,t_dew);

  /* bubble */
  for (i=0; i<1; i++)
     fprintf(fp1, "\n((xy/key/label \"z[0]=%g  numpts=%d\")\n",z[i],npts[0]);
     if (fabs(z[0])<SMALL_NUM || fabs(z[0]-1.)<SMALL_NUM || fabs(z[1])<SMALL_NUM || fabs(z[1]-1.)<SMALL_NUM)
	{
	  for (i=0;i<npts[0];i++)  
		fprintf(fp1, "%g\t %g\t \n",t_bub[i],p_bub[i]/1000.);
	}
   else
    {   
	  for (i=npts[0]-1;i>-1;i--)  
	  fprintf(fp1, "%g\t %g\t \n",t_bub[i],p_bub[i]/1000.);
	}  
  fprintf(fp1, ")\n");

  /* dew */
  for (i=0; i<1; i++)
    fprintf(fp2, "\n((xy/key/label \"z[0]=%g  numpts=%d\")\n",z[i],npts[1]); 
  for (i=0;i<npts[1];i++)  
    fprintf(fp2, "%g\t %g\t \n",t_dew[i],p_dew[i]/1000.);
  fprintf(fp2, ")\n");
  
  z[0] += 0.05;}
  }
  fclose(fp1);
  fclose(fp2);
}

For given temperature, pressure, and mixture composition, you can obtain thermodynamic properties of a mixture material in liquid, gas, and two-phase regimes using get_prop_NIST_msp. NIST implements the GERG model for thermodynamic properties of the mixtures. This model applies mixing rules to the Helmholtz energy for each mixture components. Mixture data for the binary pairs can be found in hmx.bnc provided with your Ansys Fluent installation.

Void get_prop_NIST_msp(double t, double p, double z[], double prop[]);

Function returns

double prop[]: Real array with thermodynamic properties as follows.

NIST is currently unable to calculate two-phase or mixture regime properties since all properties are relative to a pure or single phase. Ansys Fluent implements simple mixing rules based on volume fractions:

where is the bulk property, refers to a liquid or vapor phase, are the phase specific properties in vapor and liquid, and is the volume fraction of the ^th phase.

You can embed the get_prop_NIST_msp UDF access macro in a number of Fluent UDF functions, such as DEFINE_ON_DEMAND. For example, you can use get_prop_NIST_msp to build a property database with variables of temperature, pressure and composition.

To use the get_prop_NIST_msp access function, you must first enable the NIST real gas model for multi-species by entering the following text command in the Fluent console:

define/user-defined/real-gas-models/nist-multispecies-real-gas-model

use multispecies NIST real gas? [no] yes

Once the model is enabled, the list of available pure-fluid materials that you can select will be displayed.

Then enter responses to the following prompts in the console:

If the input parameters for get_prop_NIST_msp are outside the limits specified in NIST, the first element of the prop[] array, prop[NIST_q_molar]=q, will return the value of -2999.0. This indicates that NIST calculations of thermodynamic properties are questionable or simply impossible for given temperature, pressure and/or combination of materials. Since the returned value is a real double number, you can capture this error by using an appropriate conditional statement, such as

if (q > -2999.1 && q < -2998.9)

The following UDF, named getprop_msp, is called from a DEFINE_ON_DEMAND UDF Macro ( DEFINE_ON_DEMAND ). The function obtains thermodynamic properties of a mixture consisting of seven species. The species names and mass fractions are specified in the arrays spe_names[] and spe_mfractions[], respectively. (Note that the spe_mfractions[] array could also be variable.) The values of these thermodynamic properties are generated by the NIST Real Gas Model (current Version 9.1) in Ansys Fluent. A series of temperature and pressure conditions are specified in the arrays temp[] and press[], respectively.

The obtained properties values are printed in the console and stored in the NIST_output.txt file. Any errors messages are recorded in the NIST_errors.txt file.

The UDF can be executed as an interpreted or compiled UDF in Ansys Fluent.

#include "udf.h"
#include <string.h>

#define NUM_MAX 150
#define SPE_MAX 20
#define N_SPE 7
#define N_DATA 6
DEFINE_ON_DEMAND(getprop_msp)
{
  double t,p,q,sum;
  double z[SPE_MAX]={0.};
  FILE *fp1,*fp2;
  int i,j,k,n,ncomps;
  double prop[NUM_MAX]={0.};
  double temp[N_DATA]={185,200,215,200,200,200};
  double press[N_DATA]={5.e6,5.e6,5.e6,4.5e6,5.5e6,6.e6};
  char *spe_names[N_SPE]={"methane","nitrogen","carbon-dioxide","ethane","propane","isobutane","butane"};
  double spe_mfractions[N_SPE]={0.70061,0.20227,0.023246,0.053209,0.014306,0.0031167,0.0032414};

  fp1 = fopen("NIST_output.txt","w");
  fp2 = fopen("NIST_errors.txt","w");

  /* testing nist property access function */
 ncomps = N_SPE; /* number of species. to be matched by setting in fluent */
  /* composition in mass fraction */
  sum = 0.;
  for (i=0; i<N_SPE; i++)
  {
    z[i] = spe_mfractions[i];
    sum += z[i];
  }
  for (i=0; i<N_SPE;  i++)
    z[i] /= sum;

  Message0("\nComposition (Mass Fractions): %d species\n",ncomps);
  for (i=0; i<ncomps; i++)
    Message0(" %s : %f ",spe_names[i],z[i]);

  fprintf(fp1, "quality_molar, quality_mass, quality_vol, density, den_liq, den_vap, h, h_liq, h_vap,
          cp, cp_liq, cp_vap, ktc, ktc_liq, ktc_vap, mu, mu_liq, mu_vap, ");
  for (i=0; i<ncomps; i++)
    fprintf(fp1, " %s_liq, ",spe_names[i]);
  for (i=0; i<ncomps; i++)
    fprintf(fp1, " %s_vap, ",spe_names[i]);
  fprintf(fp1, " speed-of-sound");

  fprintf(fp2, "NIST calculations questionable or not possible for the following given inputs\n");
  fprintf(fp2, "\nPlease make sure the inputs are within permitted limits set by NIST!");
  fprintf(fp2, "\nTemperature    Pressure   Composition: (Mass Fractions) ");
  fprintf(fp2, "\n(K)  (Pa) ");
  for (i=0; i<ncomps; i++)
    fprintf(fp2, " %s ",spe_names[i]);

  for (k=0; k<N_DATA; k++)
  {
    t = temp[k];
    p = press[k];

    get_prop_NIST_msp(t,p,z,prop); /* call NIST property calculations */

    q = prop[NIST_q_molar]; /* error handling */
    if (q > -2999.1 && q < -2998.9)
    {
       fprintf(fp2, "\n%5.4e %5.4e ",t,p);
       for (i=0; i<ncomps; i++)
	 fprintf(fp2, " %5.4e ",z[i]);
       continue;
    }

  Message0("\n\ngetprop_msp: T=%f (K), P=%e (Bar) ",t,p/1.e5);
  Message0("\n\nquality (mol/mol)=%f  quality (kg/kg)=%f quality (vol/vol)=%f\n", prop[NIST_q_molar],
            prop[NIST_q_mass],prop[NIST_q_vol]);
  Message0("\n                           Bulk             Liquid-Phase           Vapor-Phase\n");
  Message0("\ndensity (kg/m^3):          %f       %f             %f\n",prop[NIST_den_m],
            prop[NIST_den_l],prop[NIST_den_v]);
  Message0("\nspecific-heat (kj/kg-k):   %f        %f             %f\n",prop[NIST_cp_m]/1.e3,
            prop[NIST_cp_l]/1.e3,prop[NIST_cp_v]/1.e3);
  Message0("\nthermal-ktc (mk/m-k):      %f        %f             %f\n",prop[NIST_ktc_m]*1.e3,
            prop[NIST_ktc_l]*1.e3,prop[NIST_ktc_v]*1.e3);
  Message0("\nviscosity (uPa-s):          %f        %f              %f\n",prop[NIST_mu_m]*1.e6,
            prop[NIST_mu_l]*1.e6,prop[NIST_mu_v]*1.e6);
  Message0("\nenthalpy (kj/kg):          %f        %f             %f\n",prop[NIST_h_m]/1.e3,
            prop[NIST_h_l]/1.e3,prop[NIST_h_v]/1.e3);
  Message0("\nspeed of sound (m/s):      %f        %f             %f\n",prop[NIST_a_m],
            prop[NIST_a_l],prop[NIST_a_v]);

  Message0("\nMass fractions in liquid phase: ");
  for (i=0; i<ncomps; i++)
    Message0("%s : %f  ",spe_names[i],prop[NIST_massfrac0_l+i]);
  Message0("\nMass fractions in vapor phase:  "); 
  for (i=0; i<ncomps; i++)
    Message0("%s : %f  ",spe_names[i],prop[NIST_massfrac0_v+i]);

  /* quality */
  fprintf(fp1, "\n%5.4f %5.4f %5.4f ", prop[NIST_q_molar],prop[NIST_q_mass],prop[NIST_q_vol]);
  /* density (kg/m^3) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_den_m],prop[NIST_den_l],prop[NIST_den_v]);
  /* enthalpy (KJ/Kg) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_h_m]/1.e3,prop[NIST_h_l]/1.e3,prop[NIST_h_v]/1.e3);
  /* specific-heat cp (Kj/Kg-k) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_cp_m]/1.e3,prop[NIST_cp_l]/1.e3,prop[NIST_cp_v]/1.e3);
  /* thermal conductivity (mw/m-k) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_ktc_m]*1.e3,prop[NIST_ktc_l]*1.e3,prop[NIST_ktc_v]*1.e3);
  /* viscosity (uPa-s) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_mu_m]*1.e6,prop[NIST_mu_l]*1.e6,prop[NIST_mu_v]*1.e6);

  /* Mass fractions in liquid phase */ 
  for (i=0; i<ncomps; i++)
    fprintf(fp1, "%5.4f ",prop[NIST_massfrac0_l+i]);
  /* Mass fractions in vapor phase */ 
  for (i=0; i<ncomps; i++)
    fprintf(fp1, "%5.4f ",prop[NIST_massfrac0_v+i]);

  /* speed of sound (m/s) */
  fprintf(fp1, "%5.4f %5.4f %5.4f ",prop[NIST_a_m],prop[NIST_a_l],prop[NIST_a_v]);
  }

  fclose(fp1);
  fclose(fp2);
}

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.

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

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.39: 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.

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 ).

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.

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.

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.

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.

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.

You can use F_UDMI (Table 3.40: 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.

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.

Postprocessing F_UDMI

While you cannot plot contours of F_UDMI directly, you can store the values from F_UDMI in a C_UDMI and then create a contour plot.

A UDF to transfer values from F_UDMI to C_UDMI could look like:

begin_f_loop(f, f_thread) 
{

c0 = F_C0(f,f_thread); /* Get the cell id of the cell adjacent to the face*/
t0 = F_C0_THREAD(f,f_thread); /* Get the Thread id of the cells adjacent to the face*/
C_UDMI(c0,t0,0)=F_UDMI(f,f_thread,0); /*Store the F_UDMI into cell UDMI for graphical visualization*/

}
end_f_loop(f,f_thread)

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.41: 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.

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).

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.42: 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.

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)
  } 

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)
      }
 } 

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.

/**********************************************************************
  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");
}

/**********************************************************************
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.

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.