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.
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.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 |
|---|---|---|
| | | stores the face value of a user- defined memory with
index |
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.
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 |
|---|---|---|
| | | stores the cell value of a user- defined memory with
index |
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.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 |
|---|---|---|
| | | stores the node
value of a user- defined memory with index |
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.
In the User-Defined Memory dialog
box, specify 5 for the Number of
User-Defined Memory Locations.
In the Compiled UDFs dialog box, build the compiled library named libudf for udm_res1.c and load the library.
Build the compiled library for udm_res2.c named libudf2 and load the library.
Initialize the solution.
Execute the on-demand UDFs for libudf and libudf2 in the Execute On Demand dialog box.
Iterate the solution.
Postprocess the results.
/**********************************************************************
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.