User-Defined Reaction Rate Source Terms

You can either modify the internally calculated reaction rate source terms, individual reaction rates, or define entirely new reaction rate source terms.

There are three kinds of user-coded reaction rate functions.

Custom Reaction Source Terms
Simcenter STAR-CCM+ does not initialize the source array passed in the argument to the function. Below, this user function is referred to as wdotCalculate(), although any name can be given in the user code. Custom reaction source terms are appropriate when computing reaction species sources that are not simply a multiple of the internal Arrhenius rate sources.
Modified Reaction Source Terms
Simcenter STAR-CCM+ initially evaluates the internal Arrhenius species sources, and copies this to the source array passed in the function argument list. In the example below, this user function is referred to as wdotModify(), although any name can be given in the user code. Modified Reaction Source Terms are appropriate when modifying the internal Arrhenius species sources by a factor, which is typically a constant.
Modified Internal Rates of Individual Reactions
Simcenter STAR-CCM+ initially evaluates the internal forward and backward reaction rates from Eqn. (3363) / Eqn. (3394), and copies the result to the source array that is passed in the function argument list. Below, this user function is referred to as reactionRateModify() although any name can be given in the user code. Modified reaction rates are appropriate for modifying the internally calculated reaction rates for all the reactions in the chemical mechanism.
Note For non-reversible reactions, the internally calculated reverse reaction rate is 0.

The function signature for user-defined reaction rate source terms, for both wdotModify() and wdotCalculate(), is:

 void wdotModify(double *omega, double T, unsigned int nSpe, double *zi, void *data)

The function signature for modifying rates of individual reactions reactionRateModify() is:

void reactionRateModify(double *reacRateForward, double *reacRateBackward, double T, unsigned int nSpe, double *zi, void *data)

where,


	Reactions in the Gas Phase	Surface Reactions
nSpe (type unsigned int)	The number of species in the mixture.	nSpe = nGas + nSite + nBulk (where nGas, nSite, and nBulk are the number of gas phase species, surface site species, and bulk species respectively).
zi	A pointer to a vector (type double, size nSpe) of specific mole fractions = mass fractions of the i'th species divided by the molecular weight of the i'th species (units of molecular weight are kg/kmol).	A pointer to a vector (type double, size nSpe) of gas phase specific mole fractions, surface site fractions, bulk activities, and cell temperature.
omega The default units are kmol/kg-s.	A pointer to the output vector (type double, size nSpe) of the species source terms, which are the rate of change of specific mole fractions (mass fractions of the i'th species divided by molecular weight of the i'th species).	A pointer to the output vector (type double, size nSpe) of the source terms of gas phase species specific mole fractions, surface site fractions, and bulk activities. In the case of porous chemistry, omega also has (as the last element) a cell enthalpy source term (J/kg-s).
reacRateForward	A pointer to an array (type double, size nReactions) of all reaction rates in forward direction. The default units are kmol/kg-s.	A pointer to an array (type double, size nReactions) of all surface reaction rates in forward direction. The default units are mol/cm²-s.
reacRateBackward	A pointer to an array (type double, size nReactions) of all reaction rates in backward direction. The default units are kmol/kg-s.	A pointer to an array (type double, size nReactions) of all surface reaction rates in backward direction. The default units are mol/cm²-s.
T (type double)	Temperature (K)	Wall temperature (K)
data	A pointer to the UserAccessibleData struct that is defined in UserAccessibleData.

UserAccessibleData

The UserAccessibleData allows for the transfer of data from Simcenter STAR-CCM+ to user code. To enable user coding, the following text is copied to a file and saved as UserAccessibleData.h. Then, user-accessible data are made available to the file that contains the user coding by using an include statement.

Species and reaction names are passed as part of the UserAccessibleData structure. The values in UserAccessibleData have SI units.

#ifndef _UserAccessibleData_h
#define _UserAccessibleData_h

struct UserAccessibleData {
   double _pressure; // absolute pressure (Pa)
   double _dt; // time step size (s)
   double _volume; // (m^3)
   double _volumeFraction; // liquid volume fraction of VOF model
   double _turbLen; // (m)
   double _turbTime; // (s)
   double _totalTime; // for unsteady simulations, current total time (s)

   struct FluidFilmData {
     double _fluidFilmThick; // (m)
     double _shellArea; // (m^2)
   } _fluidFilmData;

   struct SurfaceChemistryData {
     double _area; // (m^2)
     unsigned int _nGas;
     unsigned int _nBulk;
     unsigned int _nSite;
     unsigned int _isPorousRegion;
     unsigned int _nSiteMaterials;
     unsigned int _nBulkMaterials;
     unsigned int *_nSitePerMaterial;
     unsigned int *_nBulkPerMaterial;
   } _surfaceChemistryData;

   struct ReactingChannelData {
     double _massFlow; // (kg/s)
     double _velocity; // (m/s)
   } _reactingChannelData;

   struct ReactionData {
     unsigned int _nReactions;

     unsigned int *_nGasReactants;
     unsigned int *_nGasProducts;
     unsigned int *_nSiteReactants;
     unsigned int *_nSiteProducts;
     unsigned int *_nBulkReactants;
     unsigned int *_nBulkProducts;
  
     double **_gasStoichiometryReactants; 
     double **_bulkStoichiometryReactants; 
     double **_siteStoichiometryReactants; 
     double **_bulkReactantRateExponents; 
     double **_siteReactantRateExponents; 
     double **_gasReactantRateExponents;
     unsigned int **_gasReactantSpeciesIndex;
     unsigned int **_siteReactantSpeciesIndex;
     unsigned int **_bulkReactantSpeciesIndex;
  
     double **_gasStoichiometryProducts; 
     double **_bulkStoichiometryProducts; 
     double **_siteStoichiometryProducts; 
     double **_bulkProductRateExponents; 
     double **_siteProductRateExponents; 
     double **_gasProductRateExponents;
     unsigned int **_gasProductSpeciesIndex;
     unsigned int **_siteProductSpeciesIndex;
     unsigned int **_bulkProductSpeciesIndex;
   } _reactionData;

   struct ReactionPropertyDataGeneral {
     double *_lnA; // depends on reaction order (cm, mol, s, K)
     double *_b; 
     double *_E; // Ea/Ru (universal gas constant) (K)
     double *_lnA_REV; // depends on reaction order (cm, mol, s, K)
     double *_b_REV;
     double *_E_REV;  // Ea/Ru (universal gas constant) (K)
     unsigned int *_isReversible;
     unsigned int *_isREVreaction;
     char **_reactionName;
  } _reactionPropertyDataGeneral;

   struct ReactionPropertyDataFluid {
     double *_lnA_low; // depends on reaction order (cm, mol, s, K)
     double *_b_low;
     double *_E_low; // Ea/Ru (universal gas constant) (K)
     unsigned int *_hasPlog;
     unsigned int *_hasThirdBody;
     unsigned int *_hasCabm;
     unsigned int *_isBathGasReaction;
     unsigned int *_PressDepType; // 0 - no, 1-general, 2-Troe, 3-sri
     int *_bathGasMaterialIndex;
     unsigned int *_ThirdBodyCoeffSize;
     unsigned int *_PlogSize;
     unsigned int *_TroeSRISize;

     unsigned int **_ThirdBodyIndex;
     double **_ThirdBodyCoeff;
     double **_TroeSRICoeffs;
     double **_PlogCoeffs;

     unsigned int *_useElectronTemp;
     unsigned int *_isExciRxn;
     double *_exciValue; // (J)
   } _reactionPropertyDataFluid;

   struct ReactionPropertyDataSurface {
     double *_bohmCoefficient;
     unsigned int *_isReactionBohm;
     double *_stickyCoefficient;
     unsigned int *_isReactionSticky;
     unsigned int *_isMotzWiseOff;
     unsigned int *_isReactionLangmuir;
     unsigned int *_reactionCoverageFactorsSize;

     unsigned int **_coverageFactorIndex;
     double **_coverageFactorEta;  
     double **_coverageFactorMu;  
     double **_coverageFactorEaR;  
     double **_langmuirCoeffs;
   } _reactionPropertyDataSurface;
   
   struct FluidPhaseProperties {
     unsigned int _nGas;
     double *_molecularWeight; // (kg/kmol)
     double *_Tmin; // (K)
     double *_Tmid;  // (K)
     double *_Tmax; // (K)
     unsigned int *_cpHiSicoeffsSize;
     unsigned int *_cpHiSiTrangeSize;
     double **_cpHiSicoeffs; // nasa polynomial coefficients
     double **_cpHiSiTrange; // (K)
     char **_speciesName;
   } _fluidPhaseProperties;

   struct SurfaceMaterialProperties {
     double *_siteMolecularWeight; // (kg/kmol)
     double *_siteOccupancies;
     double *_siteDensity; // (kmol/m^2)
     unsigned int *_isOpenSite;
     double *_TminSite; // (K)
     double *_TmidSite; // (K)
     double *_TmaxSite; // (K)
     unsigned int*_cpHiSicoeffsSiteSize;
     unsigned int*_cpHiSiTrangeSiteSize;
     double **_cpHiSicoeffsSite; // nasa polynomial coefficients
     double **_cpHiSiTrangeSite; // (K)
     double *_bulkMolecularWeight; // (kg/kmol)
     double *_bulkDensity; // (kg/m^3)
     double *_TminBulk; // (K)
     double *_TmidBulk; // (K)
     double *_TmaxBulk; // (K)
     unsigned int*_cpHiSicoeffsBulkSize;
     unsigned int*_cpHiSiTrangeBulkSize;
     double **_cpHiSicoeffsBulk; // nasa polynomial coefficients
     double **_cpHiSiTrangeBulk; // (K)
     char **_siteSpeciesName;
     char **_bulkSpeciesName;
   } _surfaceMaterialProperties;

   struct ElectronTemperature {
     double _electronTemp;
   } _electronTemperature; 

   struct FieldFunctionsData {
     unsigned int _nFF;
     double *_ffVal;
     char **_ffName;
   } _fieldFunctionsData;
};

#endif

Note	For backward compatibility, UserAccessibleData saved in previous releases still work in the current release of Simcenter STAR-CCM+.

Modifying Reaction Source Terms

The following text is an example of a user-coded reaction rate function which modifies the internal Arrhenius species sources by multiplying them by a constant factor proportional to the pressure in each cell.

 
#include "UserAccessibleData.h"

	void wdotModify(double *omega, double T, unsigned int nSpe, double *zi, void *data)
	{
			// modify the internal Arrhenius reaction rate to be p / pref
			struct UserAccessibleData *udata = (struct UserAccessibleData *)data;
 		double const factor = udata->_pressure / 101325.;

			for( unsigned int i=0; i<nSpe +1; i++ )
				omega[i] *= factor;
	}

	void wdotJacModify(double *jac, double T, unsigned int nSpe, double *zi, void *data)
	{
 		// modify the internal Arrhenius reaction rate to be p / pref
 		struct UserAccessibleData *udata = (struct UserAccessibleData *)data;
			double const factor = data->_pressure / 101325.;

		 for( unsigned int i=0; i<(nSpe+1)*(nSpe+1); i++ )
				jac[i] *= factor;
	}

	void uclib()
	{

 	ucfunc(wdotModify, "ReactionRate", "wdot");
 	ucfunc(wdotJacModify, "ReactionRate", "wdotJac");
	}

Modifying Internal Rates of Individual Reactions

The following text is an example of a user-coded reaction rate function for modifying the rates of all individual reactions by multiplying them by a constant factor in each cell.

 #include "UserAccessibleData.h"

	void reactionRateModify(double *reacRateForward, double *reacRateBackward, double T, unsigned int nSpe, double *zi, void *data)
{
 	 struct UserAccessibleData *udata = (struct UserAccessibleData *)data;
  	unsigned int nReactions = udata->_reactionData._nReactions;
  	int i;
 
 		 for (i = 0; i < nReactions; ++i) 
  {
 		 reacRateForward[i] *= 2.0;
  		reacRateBackward[i] *= 2.0;
  }

}
/*
 	Register user-code functions
*/
	void uclib()
{
   	ucfunc(reactionRateModify, "IndividualReactionRate", "reacRateModify");
  		


}

Creating Custom Reaction Source Terms

When using user-coded reaction rates, it is strongly recommended to use the (default) Numerical option for Species Reaction Source Jacobian (under the Reacting > Reacting System Properties node). See Reacting System Properties. The functions wdotJacCalculate() and wdotJacModify() must be provided, with the following signature:

 void wdotJacModify(double *jac, double T, unsigned int nSpe, double *zi, void *data)

The double array Jacobian, of size (nSpe+1)², is the Jacobian of the vector of the species source terms plus the temperature source term. The species source terms are the rate of change of specific mole fractions.