8.16.3 The User-Defined Real Gas Model

Overview and Limitations of the User-Defined Real Gas Model

The user-defined real gas model (UDRGM) has been developed to allow you to write your own custom real gas model to fit your particular modeling needs. It also allows you to simulate a single-species flow, multiple-species mixture flow, or volumetric reactions.

The following limitations exist for the User-Defined real gas model:

• Access to the Create/Edit Materials dialog box from the navigation pane or Define menu is restricted. Therefore, if solid properties have to be set and modified, then it should be done in the Create/Edit Materials dialog box before activating the real gas model.

• All fluid zones must contain the real gas; you cannot include a real gas and another fluid in the same problem.

• Pressure-inlets, mass flow-inlets, and pressure-outlets are the only inflow and outflow boundaries available for use with the real gas models.

• Non-reflecting boundary conditions should not be used with the real gas models.

• The real gas models cannot be used with any of the multiphase models. The model is compatible with the Lagrangian Dispersed Phase Models. Please note that if you are modelling droplet or multicomponent particles, you will need to enter in the Create/Edit Materials dialog box the vaporization temperature, boiling point and latent heat of the droplet particles at the average pressure of the region where the evaporation is expected to take place. Also please take care to enter the appropriate droplet saturation vapour pressure data to cover the complete pressure/temperature range in your model. Please note that the particle material properties have to be set in the Create/Edit Materials dialog box before activating the real gas model.

• The real gas models cannot be used with the non-premixed, partially premixed, and composition PDF transport combustion models. Chemical reactions can however be modeled with the finite rate and eddy dissipation models.

The UDRGM requires a library of functions written in the C programming language. Moreover, there are certain coding requirements that need to be followed when writing these functions. Sample real gas function libraries are provided to assist you in writing your own UDRGM. When UDRGM functions are compiled, they will be grouped in a shared library which later will be loaded and linked with the ANSYS FLUENT executable. The procedure for using the UDRGM is defined below:

1.   Define the real gas equation of state and all related thermodynamic and transport property equations.

2.   Create a C source code file that conforms to the format defined in this section.

3.   Start ANSYS FLUENT and set up your case file in the usual way.

4.   Compile your UDRGM C library and build a shared library file (you can use the available compiled UDF utilities in either the graphical user interface or the text command interface).

5.   Load your newly created UDRGM library via the text command menu:

If a single-species UDRGM to be used, then the text command menu is:

    > define/user-defined/real-gas-models/user-defined-real-gas-model

    use user defined real gas? [no]  yes

On the other hand, if you are simulating multiple-species UDRGM flow, then the text command menu to use is:

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

    use user multispecies defined real gas? [no]  yes

Upon activating the UDRGM, the function library will now supply the fluid material properties for your case.

6.   You can simulate volumetric reactions with your real gas model using the Species Model dialog box, or the text interface ( define/models/species/volumetric-reactions?).

You can access the Species Model by selecting Models from the navigation pane and double-clicking Species in the task page.

In the Species Model dialog box

• Enable Species Transport under Model.

• Enable Volumetric under Reactions.

• Select the appropriate Turbulence-Chemistry Interaction option.

• Set up the reaction by clicking the Edit... button for the selected Mixture Material.

  Note that the fluid materials and their properties, appearing in the Create/Edit Materials dialog box, are the ones defined in your real gas UDF. You cannot modify the materials via this dialog box, however, you can set up the volumetric reaction. If you would like to modify the mixture materials and their properties, this should be done in the real gas UDF. The volumetric reactions for your real gas mixture are defined in the same way as for any ANSYS FLUENT mixture. For details, refer to Section  15.1.3.

  Alternatively, the chemical reactions can be set up using the define/models/ species and define/materials text command.

Note that the chemical reactions should be activated after your real gas UDF has been built and loaded. It is also recommended to test and validate your real gas UDF, running the cold flow calculation prior to attempting to solve the reacting flow. Also, make sure that the applicability range of the real gas functions in your UDF fully covers the temperature and pressure range of the reacting flow calculation.

7.   Run your calculation.

When using the UDRGM the robustness of the solver and the speed of flow convergence will largely depend on the complexity of the material properties you have defined in your UDF. It is important to understand the operational range of the property functions you are coding so you can simulate the flow within that range.

Writing the UDRGM C Function Library

Creating a UDRGM C function library is reasonably straightforward; however, your code must make use of specific function names and macros, which will be described in detail below. The basic library requirements are as follows:

• The code must contain the udf.h file inclusion directive at the beginning of the source code. This allows the definitions for DEFINE macros and other ANSYS FLUENT functions to be accessible during the compilation process.

• The code must include at least one of the UDF's DEFINE functions (i.e. DEFINE_ON_DEMAND) to be able to use the compiled UDFs utility (see the sample UDRGM codes provided below).

• Any values that are passed to the solver by the UDRGM or returned by the solver to the UDRGM are assumed to be in SI units.

• You must use the principal set of functions listed below in your UDRGM library. These functions are the mechanism by which your thermodynamic property data are transferred to the ANSYS FLUENT solver. Note that ANYNAME can be any string of alphanumeric characters, and allows you to provide unique names to your library functions.

Below, the UDRGM function names and argument lists are listed, followed by a short description of the function. Function inputs from the ANSYS FLUENT solver consist of one or more of the following variables:

	$T$	=	Temperature, K
	$p$	=	Pressure, Pa
	$\rho$	=	Density, kg/m $^3$
	$Y_i$[]	=	Species mass fraction

$Y_i$[]: ANSYS FLUENT solver returns a value of 1.0 for $Y_i$[] in single-species flows. For multiple-species flows, $Y_i$[] is a vector array containing species mass fraction in an order defined by the user setup function.

void ANYNAME_error(int err, char *f, char *msg)   prints error messages.

void ANYNAME_Setup(Domain *domain, cxboolean vapor_phase, char *filename,    int (*messagefunc)(char *format, ...), void (*errorfunc)(char *format, ...))performs model setup and initialization. Can be used to read data and parameters related to your UDRGM. When writing UDFs for multiple-species, use this function to specify the number of species and the name of the species as shown in the multiple-species example. The boolean variable, vapor_phase, passes to your UDF the setting of the text-interface command
define/user-defined/real-gas-models/set-phase.

double ANYNAME_density(double T, double P, double yi[])   returns the value of density as a function of temperature, pressure and species mass-fraction if applicable. This is your equation of state.

Since this function is called numerous times during each solver iteration, it is important to make this function as numerically efficient as possible.

double ANYNAME_specific_heat(double T, double Rho, double P, double yi[])   returns the real gas specific heat at constant pressure as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_enthalpy(double T, double Rho, double P, double yi[])    $\;\;\;$ returns the enthalpy as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_entropy(double T, double Rho, double P, double yi[])    $\;\;\;$ returns the entropy as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_mw(double yi[])   returns the fluid molecular weight.

double ANYNAME_speed_of_sound(double T, double Rho, double P, double yi[])   returns the value of speed of sound as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_viscosity(double T, double Rho, double P, double yi[])    $\;\;\;$ returns the value of dynamic viscosity as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_thermal_conductivity(double T, double Rho, double P, double yi[])   returns the value of thermal conductivity as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_rho_t(double T, double Rho, double P, double yi[])   returns the value of $\frac{d\rho}{dT}$ at constant pressure as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_rho_p(double T, double Rho, double P, double yi[])   returns the value of $\frac{d\rho}{dp}$ at constant temperature as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_enthalpy_t(double T, double Rho, double P, double yi[])    $\;\;\;$ returns the value of $\frac{dh}{dT}$ at constant pressure as a function of temperature, density, absolute pressure, and species mass-fraction if applicable. Note that by definition $dh/dt==c_p$, so this function should simply return the specific heat value.

double ANYNAME_enthalpy_p(double T, double Rho, double P, double yi[])    $\;\;\;$ returns the value of $\frac{dh}{dp}$ at constant temperature as a function of temperature, density, absolute pressure, and species mass-fraction if applicable.

double ANYNAME_enthalpy_prime( double T, double Rho, double P, double yi[], double hi[])   returns the value of the mixture enthalpy as a function of temperature, density, absolute pressure, and species mass fraction. In addition, your UDF will need to set the elements of the double array hi[] to the enthalpy of each species, in the same order as they are referenced in the mass fraction array yi[]. Note that the enthalpy in the function enthalpy_prime is defined as the sum of sensible enthalpy plus species formation enthalpy, and you should make sure that its computation is consistent with the sensible enthalpy function ANYNAME_enthalpy. The function ANYNAME_enthalpy_prime is required for the calculation of the heat of reactions, if chemical reactions are being simulated. If you are not solving reacting flows, the function ANYNAME_enthalpy_prime can simply be omitted.

At the end of the code you must define a structure of type RGAS_Function whose members are pointers to the principal functions listed above. The structure is of type RGAS_Function and its name is RealGasFunctionList.

It is imperative that the sequence of function pointers shown below be followed. Otherwise, your real gas model will not load properly into the ANSYS FLUENT code.

UDF_EXPORT  RGAS_Functions RealGasFunctionList =
{
  ANYNAME_Setup,                         /* Setup initialize  */
  ANYNAME_density,                       /* density  */
  ANYNAME_enthalpy,                      /* sensible enthalpy */
  ANYNAME_entropy,                       /* entropy  */
  ANYNAME_specific_heat,                 /* specific_heat  */
  ANYNAME_mw,                            /* molecular_weight  */
  ANYNAME_speed_of_sound,                /* speed_of_sound  */
  ANYNAME_viscosity,                     /* viscosity  */
  ANYNAME_thermal_conductivity,          /* thermal_conductivity */
  ANYNAME_rho_t,                         /* drho/dT |const p  */
  ANYNAME_rho_p,                         /* drho/dp |const T  */
  ANYNAME_enthalpy_t,                    /* dh/dT |const p  */
  ANYNAME_enthalpy_p                     /* dh/dp |const T  */
  ANYNAME_enthalpy_prime                 /* enthalpy */
};

If volumetric reactions are not being simulated, then the function ANYNAME_enthalpy_prime can be removed or ignored from the RealGasFunctionList structure shown above.

The principal set of functions shown above are the only functions in the UDRGM that will be interacting directly with the ANSYS FLUENT code. In many cases, your model may require further functions that will be called from the principal function set. For example, when multiple-species real gas model UDFs are written, the principal functions will return the mixture thermodynamic properties based on some specified mixing-law. Therefore, you may want to add further functions that will return the thermodynamic properties for the individual species. These auxiliary functions will be called from the principal set of functions. See this section in the separate UDF Manual for examples that clearly illustrate this strategy.

Compiling Your UDRGM C Functions and Building a Shared Library File

This section presents the steps you will need to follow to compile your UDRGM C code and build a shared library file. This process requires the use of a C compiler. Most UNIX operating systems provide a C compiler as a standard feature. If you are using a PC, you will need to ensure that a C ++ compiler is installed before you can proceed (e.g., Microsoft Visual C ++, v6.0 or higher). To use the UDRGM you will need to first build the UDRGM library by compiling your UDRGM C code and then load the library into the ANSYS FLUENT code. The UDRGM shared library is built in the same way that the ANSYS FLUENT executable itself is built. Internally, a script called Makefile is used to invoke the system C compiler to build an object code library that contains the native machine language translation of your higher-level C source code. This shared library is then loaded into ANSYS FLUENT (either at runtime or automatically when a case file is read) by a process called dynamic loading. The object libraries are specific to the computer architecture being used, as well as to the particular version of the ANSYS FLUENT executable being run. The libraries must, therefore, be rebuilt any time ANSYS FLUENT is upgraded, when the computer's operating system level changes, or when the job is run on a different type of computer. The general procedure for compiling UDRGM C code is as follows:

• Place the UDRGM C code in the folder, i.e., where your case file resides.

• Launch ANSYS FLUENT.

• Read your case file into ANSYS FLUENT.

• You can now compile your UDRGM C code and build a shared library file using either the graphical interface or the text command interface.

To build UDRGM library you will use the compiled UDF utilities. However, you will not use the UDF utilities to load the library. A separate loading area for the UDRGM library will be used.

Compiling the UDRGM Using the Graphical Interface

If the build is successful, then the compiled library will be placed in the appropriate architecture folder (e.g., ntx86/2d). By default the library name is libudf.so ( libudf.dll on Windows).

More information on compiled UDFs and building libraries using the ANSYS FLUENT graphical user interface can be found in the separate UDF Manual.

Compiling the UDRGM Using the Text Interface

The UDRGM library can be compiled in the text command interface as follows:

• Select the menu item

  define $\rightarrow$ user-defined $\rightarrow$ compiled-functions .

• Select the compile option.

• Enter the compiled UDF library name.

  The name given here is the name of the folder where the shared library (e.g., libudf) will reside. For example, if you hit $<$Enter $>$ then a folder should exist with the name libudf, and this folder will contain a library file called libudf. If, however, you type a new library name such as myrealgas, then a folder called myrealgas will be created and it will contain the library libudf.

• Continue on with the procedure when prompted.

• Enter the C source file names.

  Ideally you should place all of your functions into a single file. However, you can split them into separate files if desired.

• Enter the header file names, if applicable. If you do not have an extra header file then hit $<$Enter $>$ when prompted.

ANSYS FLUENT will then start compiling the UDRGM C code and put it in the appropriate architecture folder.

Example:

> define/user-defined/compiled-functions
     load OR compile ? [load]> compile

     Compiled UDF library name: ["libudf"]  my_lib


         Make sure that UDF source files are in the folder
         that contains your case and data files. If you have
         an existing libudf folder, please remove this
         folder to ensure that latest files are used.

     Continue?[yes]    <RETURN>

     Give C-Source file names:
     First file name: [""]    my_c_file.c <RETURN>

     Next  file name: [""]    <RETURN>


     Give header file names:
     First file name: [""]    my_header_file.h <RETURN>

Loading the UDRGM Shared Library File

To load the UDRGM library:

• Go to the following menu item in the text command interface.

  define $\rightarrow$ user-defined $\rightarrow$ real-gas-models

• Select either user-defined-real-gas-model if you are modeling a single-species real gas fluid or user-defined-multispecies-real-gas-model if you are modeling a multiple-species fluid-mixture.

• Turn on the real gas model.

  For single-species:

  use user defined real gas? [no]   yes
  
  

  For multiple-species:

  use multispecies user defined real gas? [no]   yes
  
  

  ANSYS FLUENT will ask for the location of the user-defined real gas library. You can enter either the name of the folder where the UDRGM shared library is called or the entire path to the UDRGM shared library.

  If the loading of the UDRGM library is successful you will see a message similar to the following:

          Opening user-defined realgas library "RealgasLibraryname"...
          Library "RealgasDirName/lnx86/2d/libudf.so" opened
          Setting material "air" to a real-gas...
          Loading Real-RealGasPrefexLable Library:
  

UDRGM Example: Ideal Gas Equation of State

This section describes an example of a user-defined real gas model. You can use this example as the basis for your own UDRGM code. In this simple example, the standard ideal gas equation of state is used in the UDRGM. See

this section in the separate UDF Manual for more examples of UDRGM functions, including multi-species real gas and reacting real-gas examples.

	$p$	=	pressure
	$T$	=	temperature
	$C_p$	=	specific heat
	$H$	=	enthalpy
	$S$	=	entropy
	$\rho$	=	density
	$c$	=	speed of sound
	$R$	=	universal gas constant/molecular weight

The ideal gas equation of state can be written in terms of pressure and temperature as

The specific heat is defined to be constant $C_p$ = 1006.42.

The enthalpy is, therefore, defined as

and entropy is given by

where $T_{\rm ref}$ = 288.15 K and $p_{\rm ref}$ = 101325 Pa

The speed of sound is simply defined as

The density derivatives are:

The enthalpy derivatives are:

When you activate the real gas model and load the library successfully into ANSYS FLUENT, you will be using the equation of state and other fluid properties from this library rather than the one built into the ANSYS FLUENT code; therefore, the access to the Create/Edit Materials dialog box will be restricted.

Ideal Gas UDRGM Code Listing

/**********************************************************************/
/* User Defined Real Gas Model :                                      */
/* For Ideal Gas Equation of State                                    */
/*                                                                    */
/**********************************************************************/
#include "udf.h"
#include "stdio.h"
#include "ctype.h"
#include "stdarg.h"

#define MW 28.966       /* molec. wt. for single gas (Kg/Kmol) */
#define RGAS (UNIVERSAL_GAS_CONSTANT/MW)

static int  (*usersMessage)(char *,...);
static void (*usersError)(char *,...);


DEFINE_ON_DEMAND(I_do_nothing)
{
  /* This is a dummy function to allow us to use */
  /* the Compiled UDFs utility                   */
}


void IDEAL_error(int err, char *f, char *msg)
{
  if (err)
    usersError("IDEAL_error (%d) from function: %s\n%s\n",err,f,msg);
}

void IDEAL_Setup(Domain *domain, cxboolean vapor_phase, char *filename,
                   int  (*messagefunc)(char *format, ...),
                   void (*errorfunc)(char *format, ...))
{
  /* Use this function for any initialization or model setups*/
  usersMessage = messagefunc;
  usersError   = errorfunc;
  usersMessage("\nLoading Real-Ideal Library: %s\n", filename);
}

double IDEAL_density(double Temp, double press, double yi[])
{
  double r = press/(RGAS*Temp); /* Density at Temp & press */

  return r;                     /* (Kg/m^3) */
}

double IDEAL_specific_heat(double Temp, double density, double P, double yi[])
{
  double cp=1006.43;

  return cp;                    /* (J/Kg/K) */
}

double IDEAL_enthalpy(double Temp, double density, double P, double yi[])
{
  double h=Temp*IDEAL_specific_heat(Temp, density, P, yi);

  return h;                     /* (J/Kg) */
}

#define TDatum 288.15
#define PDatum 1.01325e5

double IDEAL_entropy(double Temp, double density, double P, double yi[])
{
  double s=IDEAL_specific_heat(Temp,density,P,yi)*log(fabs(Temp/TDatum))+
                      RGAS*log(fabs(PDatum/P));
  return s;                     /* (J/Kg/K) */
}


double IDEAL_mw(double yi[])
{
  return MW;                    /* (Kg/Kmol) */
}

double IDEAL_speed_of_sound(double Temp, double density, double P, double yi[])
{
  double cp=IDEAL_specific_heat(Temp,density,P,yi);

  return sqrt(Temp*cp*RGAS/(cp-RGAS));  /* m/s */
}

double IDEAL_viscosity(double Temp, double density, double P, double yi[])
{
  double mu=1.7894e-05;

  return mu;                    /* (Kg/m/s) */
}

double IDEAL_thermal_conductivity(double Temp, double density, double P,
                                                   double yi[])
{
  double ktc=0.0242;

  return ktc;                   /* W/m/K */
}

double IDEAL_rho_t(double Temp, double density, double P, double yi[])
{
  /* derivative of rho wrt. Temp at constant p */
  double rho_t=-density/Temp;

  return rho_t;                 /* (Kg/m^3/K) */
}

double IDEAL_rho_p(double Temp, double density, double P, double yi[])
{
  /* derivative of rho wrt. pressure at constant T */
  double rho_p=1.0/(RGAS*Temp);

  return rho_p;                /* (Kg/m^3/Pa) */
}

double IDEAL_enthalpy_t(double Temp, double density, double P, double yi[])
{
  /* derivative of enthalpy wrt. Temp at constant p */
  return IDEAL_specific_heat(Temp, density, P, yi);
}

double IDEAL_enthalpy_p(double Temp, double density, double P, double yi[])
{
  /* derivative of enthalpy wrt. pressure  at constant T   */
  /* general form dh/dp|T = (1/rho)*[ 1 + (T/rho)*drho/dT|p] */
  /* but for ideal gas dh/dp = 0                           */
  return 0.0 ;
}

UDF_EXPORT RGAS_Functions RealGasFunctionList =
{
  IDEAL_Setup,                  /* initialize           */
  IDEAL_density,                /* density              */
  IDEAL_enthalpy,               /* enthalpy             */
  IDEAL_entropy,                /* entropy              */
  IDEAL_specific_heat,          /* specific_heat        */
  IDEAL_mw,                     /* molecular_weight     */
  IDEAL_speed_of_sound,         /* speed_of_sound       */
  IDEAL_viscosity,              /* viscosity            */
  IDEAL_thermal_conductivity,   /* thermal_conductivity */
  IDEAL_rho_t,                  /* drho/dT |const p     */
  IDEAL_rho_p,                  /* drho/dp |const T     */
  IDEAL_enthalpy_t,             /* dh/dT |const p       */
  IDEAL_enthalpy_p              /* dh/dp |const T       */
};
/**************************************************************/

Additional UDRGM Examples

You can find the following additional UDRGM examples in the separate UDF Manual :

• The Aungier Redlich Kwong equation of state for single component flow. See

  this section in the separate UDF Manual for details.

• A simple example of a multi-species real-gas model. See

  this section in the separate UDF Manual for details.

• A real gas model example with the Aungier Redlich Kwong equation of state, ideal gas mixing rules and volumetric reactions. See

  this section in the separate UDF Manual for details.