2.3.16 DEFINE_PROPERTY UDFs

Description

You can use DEFINE_PROPERTY to specify a custom material property in ANSYS FLUENT for single-phase and multiphase flows. When you are writing a user-defined mixing law UDF for a mixture material, you will need to use special utilities to access species material properties. These are described below. If you want to define a custom mass diffusivity property when modeling species transport, you must use DEFINE_DIFFUSIVITY instead of DEFINE_PROPERTY. See Section  2.3.3 for details on DEFINE_DIFFUSIVITY UDFs. For an overview of the ANSYS FLUENT solution process which shows when a DEFINE_PROPERTY UDF is called, refer to Figures  1.9.1, 1.9.2, and 1.9.3.

Some of the properties you can customize using DEFINE_PROPERTY are:

• density (as a function of temperature)

• viscosity

• thermal conductivity

• absorption and scattering coefficients

• laminar flow speed

• rate of strain

• user-defined mixing laws for density, viscosity, and thermal conductivity of mixture materials

• partially-premixed unburnt properties for unburnt density, unburnt temperature, unburnt specific heat, and unburnt thermal diffusivity

If you would like to use a UDF to define specific heat properties, you must use the DEFINE_SPECIFIC_HEAT, as described in Section  2.3.21.

Note that when you specify a user-defined density function for a compressible liquid flow application, you must also include a speed of sound function in your model. Compressible liquid density UDFs can be used in the pressure-based solver and for single phase, multiphase mixture and cavitation models, only. See the example below for details.

For Multiphase Flows

• surface tension coefficient (VOF model)

• cavitation parameters including surface tension coefficient and vaporization pressure (Mixture, cavitation models)

• heat transfer coefficient (Mixture model)

• particle or droplet diameter (Mixture model)

• speed of sound function (Mixture, cavitation models)

• density (as a function of pressure) for compressible liquid flows only (Mixture, cavitation models)

• granular temperature and viscosity (Mixture, Eulerian models)

• granular bulk viscosity (Eulerian model)

• granular conductivity (Eulerian model)

• frictional pressure and viscosity (Eulerian model)

• frictional modulus (Eulerian model)

• elasticity modulus (Eulerian model)

• radial distribution (Eulerian model)

• solids pressure (Eulerian, Mixture models)

• diameter (Eulerian, Mixture models)

Usage

DEFINE_PROPERTY( name, c, t)

Argument Type	Description
symbol name	UDF name.
cell_t c	Cell index.
Thread *t	Pointer to cell thread on which the property function is to be
	applied.
Function returns
real

There are three arguments to DEFINE_PROPERTY: name, c, and t. You supply name, the name of the UDF. c and t are variables that are passed by the ANSYS FLUENT solver to your UDF. Your UDF will need to compute the real property only for a single cell and return it to the solver.

Note that like source term UDFs, property UDFs (defined using DEFINE_PROPERTY) are called by ANSYS FLUENT from within a loop on cell threads. The solver passes all of the variables needed to allow a DEFINE_PROPERTY UDF to define a custom material, since properties are assigned on a cell basis. Consequently, your UDF will not need to loop over cells in a zone since ANSYS FLUENT is already doing it.

Auxiliary Utilities

Some commonly-used auxiliary utilities for custom property UDFs are described below. They are generic_property, MATERIAL_PROPERTY, THREAD_MATERIAL, and mixture_species_loop.

generic_property is a general purpose function that returns the real value for the given property id for the given thread material. It is defined in prop.h and is used only for species properties.

The following Property_ID variables are available:

• PROP_rho, density

• PROP_mu, viscosity

• PROP_ktc, thermal conductivity

generic_property ( name, c, t, prop, id, T)

Argument Type	Description
symbol name	Function name.
cell_t c	Cell index.
Thread *t	Pointer to cell thread on which property function is to be
	applied.
Property *prop	Pointer to property array for the thread material that can be
	obtained through the macro MATERIAL_PROPERTY(m) See below.
Property_ID id	Property ID of the required property you want to define a
	custom mixing law for (e.g., PROP_ktc for thermal conductivity).
	See below for list of variables.
real T	Temperature at which the property is to be evaluated (used only
	if a polynomial method is specified).
Function returns
real

MATERIAL_PROPERTY is defined in materials.h and returns a real pointer to the Property array prop for the given material pointer m.

MATERIAL_PROPERTY(m)
Argument Type	Description
Material *m	Material pointer.
Function returns
real

THREAD_MATERIAL is defined in threads.h and returns real pointer m to the Material that is associated with the given cell thread t.

Note that in previous versions of FLUENT, THREAD_MATERIAL took two arguments ( t,i), but now only takes one ( t).

THREAD_MATERIAL(t)
Argument Type	Description
Thread *t	Pointer to cell thread.
Function returns
real

mixture_species_loop is defined in materials.h and loops over all of the species for the given mixture material.

mixture_species_loop (m,sp,i)
Argument Type	Description
Material *m	Material pointer.
Material *sp	Species pointer.
int i	Species index.
Function returns
real

Example 1 - Temperature-dependent Viscosity Property

The following UDF, named cell_viscosity, generates a variable viscosity profile to simulate solidification. The function is called for every cell in the zone. The viscosity in the warm ( $T > 288$ K) fluid has a molecular value for the liquid (5.5 $\times 10^{-3 }$kg/m-s), while the viscosity for the cooler region ( $T <$ 286 K) has a much larger value (1.0 kg/m-s). In the intermediate temperature range (286 K $\leq T \leq$ 288 K), the viscosity follows a linear profile that extends between the two values given above:

This model is based on the assumption that as the liquid cools and rapidly becomes more viscous, its velocity will decrease, thereby simulating solidification. Here, no correction is made for the energy field to include the latent heat of freezing. The source code can be interpreted or compiled in ANSYS FLUENT.

/*********************************************************************
   UDF that simulates solidification by specifying a temperature-    
   dependent viscosity property                                      
**********************************************************************/
#include "udf.h"

DEFINE_PROPERTY(cell_viscosity,c,t)
{
  real mu_lam;
  real temp = C_T(c,t);

  if (temp > 288.)
    mu_lam = 5.5e-3;
  else if (temp > 286.)
    mu_lam = 143.2135 - 0.49725 * temp;
  else
    mu_lam = 1.;

  return mu_lam;
}

The function cell_viscosity is defined on a cell. Two real variables are introduced: temp, the value of C_T(c,t), and mu_lam, the laminar viscosity computed by the function. The value of the temperature is checked, and based upon the range into which it falls, the appropriate value of mu_lam is computed. At the end of the function the computed value for the viscosity ( mu_lam) is returned to the solver.

Example 2 - User-defined Mixing Law for Thermal Conductivity

You can use DEFINE_PROPERTY to define custom user-defined mixing laws for density, viscosity, and conductivity of mixture materials. In order to access species material properties your UDF will need to utilize auxiliary utilities that are described above.

The following UDF, named mass_wtd_k, is an example of a mass-fraction weighted conductivity function. The UDF utilizes the generic_property function to obtain properties of individual species. It also makes use of MATERIAL_PROPERTY and THREAD_MATERIAL.

/*********************************************************************
  UDF that specifies a custom mass-fraction weighted conductivity   
**********************************************************************/
#include "udf.h"

DEFINE_PROPERTY(mass_wtd_k,c,t)
{
    real sum = 0.; int i;
    Material *sp;
    real ktc;
    Property *prop;
    mixture_species_loop(THREAD_MATERIAL(t),sp,i)
      {
        prop = (MATERIAL_PROPERTY(sp));
        ktc = generic_property(c,t,prop,PROP_ktc,C_T(c,t));
        sum += C_YI(c,t,i)*ktc;
      }
    return sum;
}

Example 3 - Surface Tension Coefficient UDF

DEFINE_PROPERTY can also be used to define a surface tension coefficient UDF for the multiphase VOF model. The following UDF specifies a surface tension coefficient as a quadratic function of temperature. The source code can be interpreted or compiled in ANSYS FLUENT.

/***************************************************************
Surface Tension Coefficient UDF for the multiphase VOF Model
***************************************************************/

#include "udf.h"
DEFINE_PROPERTY(sfc,c,t)
{
    real T = C_T(c,t);
    return 1.35 - 0.004*T + 5.0e-6*T*T;
}

Note that surface tension UDFs for the VOF and Mixture multiphase models are both hooked to ANSYS FLUENT in the Phase Interaction dialog box, but in different ways. For the VOF model, the function hook is located in the Surface Tension tab in the dialog box. For the Mixture model, however, the function hook is located in the Mass tab, and will become visible upon selecting the Cavitation option.

Example 4 - Density Function for Compressible Liquids

Liquid density is not a constant but is instead a function of the pressure field. In order to stabilize the pressure solution for compressible flows in ANSYS FLUENT, an extra term related to the speed of sound is needed in the pressure correction equation. Consequently, when you want to define a custom density function for a compressible flow, your model must also include a speed of sound function. Although you can direct ANSYS FLUENT to calculate a speed of sound function by choosing one of the available methods (e.g., piecewise-linear, polynomial) in the Create/Edit Materials dialog box, as a general guideline you should define a speed of sound function along with your density UDF using the formulation:

For simplicity, it is recommended that you concatenate the density and speed of sound functions into a single UDF source file.

The following UDF source code example contains two concatenated functions: a density function named superfluid_density that is defined in terms of pressure and a custom speed of sound function named sound_speed.

/********************************************************************
Density and speed of sound UDFs for compressible liquid flows.
For use with pressure-based solver, for single phase, multiphase mixture
or cavitation models only.
Note that for density function, dp is the difference between a cell 
absolute pressure and reference pressure.
*********************************************************************/
#include "udf.h" 

#define BMODULUS 2.2e9
#define rho_ref 1000.0
#define p_ref 101325

DEFINE_PROPERTY(superfluid_density, c, t)
{
    real rho;
    real p, dp;
    real p_operating;
    
    p_operating = RP_Get_Real ("operating-pressure");
    
    p = C_P(c,t) + p_operating;
    dp = p-p_ref;
    rho = rho_ref/(1.0-dp/BMODULUS);
    return rho;
}


DEFINE_PROPERTY(sound_speed, c,t)

{
    real a; 
    real p, dp,p_operating;

    p_operating = RP_Get_Real ("operating-pressure");
 
    p = C_P(c,t) + p_operating;
    dp = p-p_ref; 
    a = (1.-dp/BMODULUS)*sqrt(BMODULUS/rho_ref);   
    return a;
}

Hooking a Property UDF to ANSYS FLUENT

After the UDF that you have defined using DEFINE_PROPERTY is interpreted (Chapter  4) or compiled (Chapter  5), the name of the argument that you supplied as the first DEFINE macro argument (e.g., sound_speed) will become visible and selectable in dialog boxes in ANSYS FLUENT.
See Section  6.2.16 for details.