2.2.6 DEFINE_EXECUTE_ON_LOADING

Description

DEFINE_EXECUTE_ON_LOADING is a general-purpose macro that can be used to specify a function that executes as soon as a compiled UDF library is loaded in ANSYS FLUENT. This is useful when you want to initialize or setup UDF models when a UDF library is loaded. (Alternatively, if you save your case file when a shared library is loaded, then the UDF will execute whenever the case file is subsequently read.)

Compiled UDF libraries are loaded using either the Compiled UDFs or the UDF Library Manager dialog box (see Section  5.5). An EXECUTE_ON_LOADING UDF is the best place to reserve user-defined scalar (UDS) and user-defined memory (UDM) for a particular library (Sections  3.2.8 and 3.2.9) as well as set UDS and UDM names (Sections  3.2.8 and 3.2.9).

DEFINE_EXECUTE_ON_LOADING UDFs can be executed only as compiled UDFs.

Usage

DEFINE_EXECUTE_ON_LOADING( name, libname)

Argument Type	Description
symbol name	UDF name.
char *libname	compiled UDF library name.
Function returns
void

There are two arguments to DEFINE_EXECUTE_ON_LOADING: name and libname. You supply a name for the UDF which will be used by ANSYS FLUENT when reporting that the EXECUTE_ON_LOADING UDF is being run. The libname is set by ANSYS FLUENT to be the name of the library (e.g., libudf) that you have specified (by entering a name or keeping the default libudf). libname is passed so that you can use it in messages within your UDF.

Example 1

The following simple UDF named report_version, prints a message on the console that contains the version and release number of the library being loaded.

#include "udf.h"

static int version = 1;
static int release = 2;

DEFINE_EXECUTE_ON_LOADING(report_version, libname)
{
    Message("\nLoading %s version %d.%d\n",libname,version,release);
}

Example 2

The following source code contains two UDFs. The first UDF is an EXECUTE_ON_LOADING function that is used to reserve three UDMs (using Reserve_User_Memory_Vars) for a library and set unique names for the UDM locations (using Set_User_Memory_Name). The second UDF is an ON_DEMAND function 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 udm_offset, which is defined in the 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. See Sections  3.2.9 and 3.2.9 for more information on reserving and naming UDMs.

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

Hooking an Execute On Loading UDF to ANSYS FLUENT

After the UDF that you have defined using DEFINE_EXECUTE_ON_LOADING is compiled (Chapter  5), the function will not need to be hooked to ANSYS FLUENT through any graphics dialog boxes. Instead, ANSYS FLUENT searches the newly-loaded library for any UDFs of the type EXECUTE_ON_LOADING, and will automatically execute them in the order they appear in the library.