7.16.5. 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, multiphase flow, or volumetric reactions.

The following limitations exist for the UDRGM:

7.16.5.1. Limitations of the User-Defined Real Gas Model

  • You cannot include more than one user-defined real gas material (fluid or mixture) in the same problem. However, you can use other materials together with real gas in your simulation.

  • When you are using the UDRGM, the materials defined in your real gas UDF will appear in the Create/Edit Materials Dialog Box with the name real-gas-fluid or real-gas-mixture and all physical and thermodynamic property inputs disabled. Use the Create/Edit Materials Dialog Box to define or modify:

    • Mass diffusivity property in the real-gas-mixture material if you are modeling multicomponent flow.

    • Chemical reactions in the real-gas-mixture if you are modeling reacting flow.

    • Radiation properties for the real-gas-mixture or the real-gas-fluid materials if you are modeling radiation.

    • Properties of materials other than the user-defined real-gas-mixture or real-gas-fluid materials.


    Note:  If you are using the UDRGM together with other materials from ANSYS Fluent's property database in dispersed phase or multiphase calculations, take care to use the same reference temperature as in ANSYS Fluent in your real-gas UDF. The reference temperature in ANSYS Fluent is 298.15 K.


  • 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 are not compatible with the real gas models when using the density-based solver. If your model requires NRBC and a real gas model, you must use the pressure-based solver.

  • The UDRGM can be used with the Eulerian multiphase models.


    Note:  Note the following restrictions:

    • Only one phase can be a real gas.


  • The UDRGM is compatible with the Lagrangian Dispersed Phase Models. Refer to Using the Cubic Equation of State Models with the Lagrangian Dispersed Phase Models for guidelines and restrictions of this approach.

  • 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. Note that the Dimension Reduction model is not available with the real gas 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 that later will be loaded and linked with the ANSYS Fluent executable. The procedure for using the UDRGM is defined as follows:

  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 from the tree by going to Setup/Models/Species and double-clicking Species.

    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 real-gas-mixture Mixture Material.


      Important:  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 Defining Reactions.


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


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

7.16.5.2. 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 (that is 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.

Function inputs from the ANSYS Fluent solver consist of one or more of the following variables:

  = Temperature, K
  = Pressure, Pa
  = Density, kg/
  [] = Species mass fraction

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


The UDRGM function names and argument lists, followed by a short description of the function, are as follows:

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(cxboolean vapor_phase, double T, double P, double yi[])

returns the value of density as a function of phase, temperature, pressure and species mass-fraction if applicable. The Boolean variable vapor_phase passes to your UDF the setting of the text-interface command define/user-defined/real-gas-models/set-phase, or, if applicable, the zone phase set by the text-interface command define/boundary-conditions/modify-zones/change-zone-phase.


Important:  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 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 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 at constant pressure as a function of temperature, density, absolute pressure, and species mass-fraction if applicable. Note that by definition , 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 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 must 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.


Important:  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 described here.

The principal set of functions described 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 User-Defined Real Gas Models (UDRGM) in the Fluent Customization Manual for examples that clearly illustrate this strategy.

7.16.5.3. Compiling Your UDRGM C Functions and Building a Shared Library File

This section presents the steps you must follow to compile your UDRGM C code and build a shared library file. This process requires the use of a C compiler. For more details on compiler requirements, see Compilers in the Fluent Customization Manual. To use the UDRGM you must 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 run time 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, that is, 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.


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


7.16.5.3.1. Compiling the UDRGM Using the Graphical Interface

If the build is successful, then the compiled library will be placed in the appropriate architecture folder (for example, win64/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 Fluent Customization Manual.

7.16.5.3.2. 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 → user-defined → compiled-functions .

  • Select the compile option.

  • Enter the compiled UDF library name.


    Important:  The name given here is the name of the folder where the shared library (for example, libudf) will reside. For example, if you press 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.


    Important:  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 press 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


7.16.5.3.3. Loading the UDRGM Shared Library File

Load the UDRGM library:

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

    define → user-defined → real-gas-models

  • Select one of the following

    • user-defined-real-gas-model if you are modeling a single-species real gas fluid

    • 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/lnamd64/2d/libudf.so" opened
       Setting material "air" to a real-gas...
       Loading Real-RealGasPrefexLable Library: 
    

7.16.5.4. 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 User-Defined Real Gas Models (UDRGM) in the Fluent Customization Manual for more examples of UDRGM functions, including multi-species real gas and reacting real-gas examples.

  = pressure
  = temperature
  = specific heat
  = enthalpy
  = entropy
  = density
  = speed of sound
  = universal gas constant/molecular weight

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

(7–119)

The specific heat is defined to be constant = 1006.42.

The enthalpy is, therefore, defined as

(7–120)

and entropy is given by

(7–121)

where = 288.15 K and = 101325 Pa

The speed of sound is simply defined as

(7–122)

The density derivatives are:

(7–123)

(7–124)

The enthalpy derivatives are:

(7–125)

(7–126)

When you enable 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.

7.16.5.4.1. 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(cxboolean vapor_phase, 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  */
 };
 /**************************************************************/

7.16.5.5. Additional UDRGM Examples

You can find the following additional UDRGM examples in the Fluent Customization Manual:


Release 18.2 - © ANSYS, Inc. All rights reserved.