Cantera  2.1.2
VCSnonideal Namespace Reference

Contains classes and functions implementing the VCS multi-phase equilibrium solver. More...

## Classes

class  DoubleStarStar
A class for 2D double arrays stored in column-major (Fortran-compatible) form. More...

class  VCS_COUNTERS
Class to keep track of time and iterations. More...

class  IntStarStar
A class for 2D int arrays stored in column-major (Fortran-compatible) form. More...

class  vcs_MultiPhaseEquil
Cantera's Interface to the Multiphase chemical equilibrium solver. More...

class  VCS_PROB
Interface class for the vcs thermo equilibrium solver package, which generally describes the problem to be solved. More...

class  VCS_SOLVE
This is the main structure used to hold the internal data used in vcs_solve_TP(), and to solve TP systems. More...

class  VCS_SPECIES_THERMO

class  vcs_SpeciesProperties
Properties of a single species. More...

class  vcs_VolPhase
Phase information and Phase calculations for vcs. More...

## Typedefs

typedef double(* VCS_FUNC_PTR )(double xval, double Vtarget, int varID, void *fptrPassthrough, int *err)
Definition of the function pointer for the root finder. More...

## Functions

static void print_char (const char letter, const int num)
print char repeatedly to log file More...

int vcs_Cantera_to_vprob (Cantera::MultiPhase *mphase, VCSnonideal::VCS_PROB *vprob)
Translate a MultiPhase object into a VCS_PROB problem definition object. More...

int vcs_Cantera_update_vprob (Cantera::MultiPhase *mphase, VCSnonideal::VCS_PROB *vprob)
Translate a MultiPhase information into a VCS_PROB problem definition object. More...

static void print_space (int num)

static void print_char (const char letter, const int num)

static int basisOptMax1 (const double *const molNum, const int n)

static void print_space (int num)

static void print_line (const std::string &schar, size_t num)

static void print_funcEval (FILE *fp, double xval, double fval, int its)

int vcsUtil_root1d (double xmin, double xmax, size_t itmax, VCS_FUNC_PTR func, void *fptrPassthrough, double FuncTargVal, int varID, double *xbest, int printLvl=0)
One dimensional root finder. More...

static void printProgress (const vector< string > &spName, const vector< double > &soln, const vector< double > &ff)

static void print_space (size_t num)

void vcs_dzero (double *vector, int length)

void vcs_izero (int *vector, int length)

void vcs_dcopy (double *const vec_to, const double *const vec_from, int length)

void vcs_icopy (int *vec_to, int *vec_from, int length)

void vcs_vdzero (std::vector< double > &vvv, int len)

double vcs_l2norm (const std::vector< double > vec)
determine the l2 norm of a vector of doubles More...

void vcs_vizero (std::vector< int > &vvv, int len)

void vcs_vdcopy (std::vector< double > &vec_to, const std::vector< double > &vec_from, int length)

void vcs_vicopy (std::vector< int > &vec_to, const std::vector< int > &vec_from, const int length)
Copy one std integer vector into another. More...

size_t vcs_optMax (const double *x, const double *xSize, size_t j, size_t n)
Finds the location of the maximum component in a double vector. More...

int vcs_max_int (const int *vector, int length)
Returns the maximum integer in a list. More...

static void vcsUtil_swapRows (double *c, size_t idem, size_t n, double *b, size_t m, size_t irowa, size_t irowb)
Swap rows in the c matrix and the b rhs matrix. More...

static void vcsUtil_mlequ_preprocess (double *c, size_t idem, size_t n, double *b, size_t m)
Swap rows in the c matrix and the b rhs matrix to lower the condition number of the matrix. More...

int vcsUtil_mlequ (double *c, size_t idem, size_t n, double *b, size_t m)
Invert an n x n matrix and solve m rhs's. More...

int vcsUtil_gaussj (double *c, size_t idem, size_t n, double *b, size_t m)
Invert an n x n matrix and solve m rhs's. More...

double vcsUtil_gasConstant (int mu_units)
Returns the value of the gas constant in the units specified by parameter. More...

void vcs_print_line (const char *str, int num)
Prints a line consisting of multiple occurrences of the same string. More...

const char * vcs_speciesType_string (int speciesStatus, int length=100)
Returns a const char string representing the type of the species given by the first argument. More...

void vcs_print_stringTrunc (const char *str, size_t space, int alignment)
Print a string within a given space limit. More...

bool vcs_doubleEqual (double d1, double d2)
Simple routine to check whether two doubles are equal up to roundoff error. More...

void vcs_heapsort (std::vector< int > &x)
Sorts a vector of ints in place from lowest to the highest values. More...

void vcs_orderedUnique (std::vector< int > &xOrderedUnique, const std::vector< int > &x)
Sorts a vector of ints and eliminates duplicates from the resulting list. More...

std::string string16_EOSType (int EOSType)
Return a string representing the equation of state. More...

static bool hasChargedSpecies (const Cantera::ThermoPhase *const tPhase)
This function decides whether a phase has charged species or not. More...

static bool chargeNeutralityElement (const Cantera::ThermoPhase *const tPhase)

double vcs_second ()
Returns the system wall clock time in seconds. More...

void vcs_dzero (double *const vec_to, const size_t length)
Zero a double vector. More...

void vcs_izero (int *const vec_to, const size_t length)
Zero an int vector. More...

void vcs_dcopy (double *const vec_to, const double *const vec_from, const size_t length)
Copy a double vector. More...

void vcs_icopy (int *const vec_to, const int *const vec_from, const size_t length)
Copy an int vector. More...

void vcs_vdzero (std::vector< double > &vec_to, const size_t length)
Zero a std double vector. More...

void vcs_vizero (std::vector< int > &vec_to, const size_t length)
Zero a std int vector. More...

void vcs_vdcopy (std::vector< double > &vec_to, const std::vector< double > &vec_from, size_t length)
Copy one std double vector into another. More...

## Variables

static char pprefix [20] = " --- vcs_inest: "

int vcs_timing_print_lvl = 1
Global hook for turning on and off time printing. More...

## Detailed Description

Contains classes and functions implementing the VCS multi-phase equilibrium solver.

## Typedef Documentation

 typedef double(* VCS_FUNC_PTR)(double xval, double Vtarget, int varID, void *fptrPassthrough, int *err)

Definition of the function pointer for the root finder.

see vcsUtil_root1d for a definition of how to use this.

Definition at line 185 of file vcs_internal.h.

## Function Documentation

 static void VCSnonideal::print_char ( const char letter, const int num )
static

print char repeatedly to log file

Parameters
 letter letter to be repeated num Number of times repeated

Definition at line 884 of file vcs_MultiPhaseEquil.cpp.

References plogf.

Referenced by VCS_PROB::prob_report(), vcs_Cantera_to_vprob(), and vcs_Cantera_update_vprob().

 int vcs_Cantera_to_vprob ( Cantera::MultiPhase * mphase, VCSnonideal::VCS_PROB * vprob )
 int vcs_Cantera_update_vprob ( Cantera::MultiPhase * mphase, VCSnonideal::VCS_PROB * vprob )

Translate a MultiPhase information into a VCS_PROB problem definition object.

This version updates the problem statement information only. All species and phase definitions remain the same.

Parameters
 mphase MultiPhase object that is the source for all of the information vprob VCS_PROB problem definition that gets all of the information

Definition at line 1304 of file vcs_MultiPhaseEquil.cpp.

 int vcsUtil_root1d ( double xmin, double xmax, size_t itmax, VCS_FUNC_PTR func, void * fptrPassthrough, double FuncTargVal, int varID, double * xbest, int printLvl = 0 )

One dimensional root finder.

This root finder will find the root of a one dimensional equation

$f(x) = 0$

where x is a bounded quantity: $$x_{min} < x < x_max$$

The function to be minimized must have the following call structure:

typedef double (*VCS_FUNC_PTR)(double xval, double Vtarget,
int varID, void *fptrPassthrough,
int *err);

xval is the current value of the x variable. Vtarget is the requested value of f(x), usually 0. varID is an integer that is passed through. fptrPassthrough is a void pointer that is passed through. err is a return error indicator. err = 0 is the norm. anything else is considered a fatal error. The return value of the function is the current value of f(xval).

Parameters
 xmin Minimum permissible value of the x variable xmax Maximum permissible value of the x parameter itmax Maximum number of iterations func function pointer, pointing to the function to be minimized fptrPassthrough Pointer to void that gets passed through the rootfinder, unchanged, to the func. FuncTargVal Target value of the function. This is usually set to zero. varID Variable ID. This is usually set to zero. xbest Pointer to the initial value of x on input. On output This contains the root value. printLvl Print level of the routine.

Following is a nontrial example for vcs_root1d() in which the position of a cylinder floating on the water is calculated.

#include <cmath>
#include <cstdlib>
const double g_cgs = 980.;
const double mass_cyl = 0.066;
const double diam_cyl = 0.048;
const double rad_cyl = diam_cyl / 2.0;
const double len_cyl = 5.46;
const double vol_cyl = Pi * diam_cyl * diam_cyl / 4 * len_cyl;
const double rho_cyl = mass_cyl / vol_cyl;
const double rho_gas = 0.0;
const double rho_liq = 1.0;
const double sigma = 72.88;
const double alpha1 = 40.0 / 180. * Pi;
double func_vert(double theta1, double h_2, double rho_c) {
double f_grav = - Pi * rad_cyl * rad_cyl * rho_c * g_cgs;
double tmp1 = theta1 + sin(theta1) * cos(theta1) - 2.0 * h_2 / rad_cyl * sin(theta1);
double f_buoy = tmp * (Pi * rho_gas + (rho_liq - rho_gas) * tmp1);
double f_sten = 2 * sigma * sin(theta1 + alpha1 - Pi);
return f_grav + f_buoy + f_sten;
}
double calc_h2_farfield(double theta1) {
double rhs = sigma * (1.0 + cos(alpha1 + theta1));
rhs *= 2.0;
rhs = rhs / (rho_liq - rho_gas) / g_cgs;
double sign = -1.0;
if (alpha1 + theta1 < Pi) sign = 1.0;
double res = sign * sqrt(rhs);
return res + rad_cyl * cos(theta1);
}
double funcZero(double xval, double Vtarget, int varID, void *fptrPassthrough, int *err) {
double theta = xval;
double h2 = calc_h2_farfield(theta);
return func_vert(theta, h2, rho_cyl);
}
int main () {
double thetamax = Pi;
double thetamin = 0.0;
int maxit = 1000;
int iconv;
double thetaR = Pi/2.0;
int printLvl = 4;
iconv = VCSnonideal::vcsUtil_root1d(thetamin, thetamax, maxit,
funcZero,
(void *) 0, 0.0, 0,
&thetaR, printLvl);
printf("theta = %g\n", thetaR);
double h2Final = calc_h2_farfield(thetaR);
printf("h2Final = %g\n", h2Final);
return 0;
}

Definition at line 34 of file vcs_root1d.cpp.

References plogf, VCS_SUCCESS, and vcsUtil_mlequ().

 double vcs_l2norm ( const std::vector< double > vec )

determine the l2 norm of a vector of doubles

Parameters
 vec vector of doubles
Returns
Returns the l2 norm of the vector

Definition at line 69 of file vcs_util.cpp.

Referenced by VCS_SOLVE::vcs_phaseStabilityTest().

 void vcs_vicopy ( std::vector< int > & vec_to, const std::vector< int > & vec_from, const int length )
inline

Copy one std integer vector into another.

This is an inlined function that uses memcpy. memcpy is probably the fastest way to do this.

Parameters
 vec_to Vector to copy into. This vector must be dimensioned at least as large as the vec_from vector. vec_from Vector to copy from length Number of integers to copy.

Definition at line 103 of file vcs_util.cpp.

 size_t vcs_optMax ( const double * x, const double * xSize, size_t j, size_t n )

Finds the location of the maximum component in a double vector.

Parameters
 x pointer to a vector of doubles xSize pointer to a vector of doubles used as a multiplier to x[] before making the decision. Ignored if set to NULL. j lowest index to search from n highest index to search from
Returns
Return index of the greatest value on X(i) searched j <= i < n

Definition at line 110 of file vcs_util.cpp.

Referenced by VCS_SOLVE::vcs_report().

 int vcs_max_int ( const int * vector, int length )

Returns the maximum integer in a list.

Parameters
 vector pointer to a vector of ints length length of the integer vector
Returns
returns the max integer value in the list

Definition at line 136 of file vcs_util.cpp.

 static void VCSnonideal::vcsUtil_swapRows ( double * c, size_t idem, size_t n, double * b, size_t m, size_t irowa, size_t irowb )
static

Swap rows in the c matrix and the b rhs matrix.

Parameters
 c Matrix of size nxn, row first idem C storage dimension for the number of rows n Size of the matrix b RHS of the Ax=b problem to solve m Number of rhs to solve irowa first row to swap irowb second row to swap

Definition at line 189 of file vcs_util.cpp.

Referenced by vcsUtil_gaussj(), and vcsUtil_mlequ_preprocess().

 static void VCSnonideal::vcsUtil_mlequ_preprocess ( double * c, size_t idem, size_t n, double * b, size_t m )
static

Swap rows in the c matrix and the b rhs matrix to lower the condition number of the matrix.

Parameters
 c Matrix of size nxn, row first idem C storage dimension for the number of rows n Size of the matrix b RHS of the Ax=b problem to solve m Number of rhs to solve

Definition at line 211 of file vcs_util.cpp.

References Cantera::npos, and vcsUtil_swapRows().

Referenced by vcsUtil_gaussj(), and vcsUtil_mlequ().

 int vcsUtil_mlequ ( double * c, size_t idem, size_t n, double * b, size_t m )

Invert an n x n matrix and solve m rhs's.

Solve a square matrix with multiple right hand sides

$C X + B = 0;$

This routine uses Gauss elimination and is optimized for the solution of lots of rhs's. A crude form of row pivoting is used here. The matrix C is destroyed during the solve.

Returns
The solution x[] is returned in the matrix B. Routine returns an integer representing success:
• 1 : Matrix is singular
• 0 : solution is OK
Parameters
 c Matrix to be inverted. c is in fortran format, i.e., rows are the inner loop. Row numbers equal to idem. c[i+j*idem] = c_i_j = Matrix to be inverted: i = row number j = column number idem number of row dimensions in c n Number of rows and columns in c b Multiple RHS. Note, b is actually the negative of most formulations. Row numbers equal to idem. b[i+j*idem] = b_i_j = vectors of rhs's: i = row number j = column number (each column is a new rhs) m number of rhs's

Definition at line 297 of file vcs_util.cpp.

References plogf, and vcsUtil_mlequ_preprocess().

Referenced by VCS_SOLVE::vcs_elcorr(), and vcsUtil_root1d().

 int vcsUtil_gaussj ( double * c, size_t idem, size_t n, double * b, size_t m )

Invert an n x n matrix and solve m rhs's.

Solve a square matrix with multiple right hand sides

$C X + B = 0;$

This routine uses Gauss-Jordan elimination and is optimized for the solution of lots of rhs's. Full row and column pivoting is used here. It's been shown to be necessary in at least one case. The matrix C is destroyed during the solve.

Returns
The solution x[] is returned in the matrix B. Routine returns an integer representing success:
• 1 : Matrix is singular
• 0 : solution is OK
Parameters
 c Matrix to be inverted. c is in fortran format, i.e., rows are the inner loop. Row numbers equal to idem. c[i+j*idem] = c_i_j = Matrix to be inverted: i = row number j = column number idem number of row dimensions in c n Number of rows and columns in c b Multiple RHS. Note, b is actually the negative of most formulations. Row numbers equal to idem. b[i+j*idem] = b_i_j = vectors of rhs's: i = row number j = column number (each column is a new rhs) m number of rhs's

Definition at line 408 of file vcs_util.cpp.

References Cantera::npos, plogf, vcsUtil_mlequ_preprocess(), and vcsUtil_swapRows().

Referenced by VCS_SOLVE::vcs_basopt().

 double vcsUtil_gasConstant ( int mu_units )

Returns the value of the gas constant in the units specified by parameter.

Parameters
 mu_units Specifies the units. VCS_UNITS_KCALMOL: kcal gmol-1 K-1 VCS_UNITS_UNITLESS: 1.0 K-1 VCS_UNITS_KJMOL: kJ gmol-1 K-1 VCS_UNITS_KELVIN: 1.0 K-1 VCS_UNITS_MKS: joules kmol-1 K-1 = kg m2 s-2 kmol-1 K-1

Definition at line 506 of file vcs_util.cpp.

References Cantera::GasConst_cal_mol_K, Cantera::GasConstant, and plogf.

 void vcs_print_line ( const char * str, int num )

Prints a line consisting of multiple occurrences of the same string.

This prints a string num times, and then terminate with a end of line character

Parameters
 str C string that is null terminated num number of times the string is to be printed

Definition at line 534 of file vcs_util.cpp.

References plogendl, and plogf.

 const char * vcs_speciesType_string ( int speciesStatus, int length = 100 )

Returns a const char string representing the type of the species given by the first argument.

Parameters
 speciesStatus Species status integer representing the type of the species. length Maximum length of the string to be returned. Shorter values will yield abbreviated strings. Defaults to a value of 100.

Definition at line 544 of file vcs_util.cpp.

Referenced by VCS_SOLVE::vcs_evaluate_speciesType(), and VCS_SOLVE::vcs_RxnStepSizes().

 void vcs_print_stringTrunc ( const char * str, size_t space, int alignment )

Print a string within a given space limit.

This routine limits the amount of the string that will be printed to a maximum of "space" characters. Printing is done to to Cantera's writelog() function.

Parameters
 str String, which must be null terminated. space space limit for the printing. alignment Alignment of string within the space: 0 centered 1 right aligned 2 left aligned

Definition at line 614 of file vcs_util.cpp.

References plogf.

Referenced by VCS_SOLVE::vcs_basopt().

 bool vcs_doubleEqual ( double d1, double d2 )

Simple routine to check whether two doubles are equal up to roundoff error.

Currently it's set to check for 10 digits of relative accuracy.

Parameters
 d1 first double d2 second double
Returns
returns true if the doubles are "equal" and false otherwise

Definition at line 645 of file vcs_util.cpp.

 void vcs_heapsort ( std::vector< int > & x )

Sorts a vector of ints in place from lowest to the highest values.

The vector is returned sorted from lowest to highest.

Parameters
 x Reference to a vector of ints.
Deprecated:

Definition at line 655 of file vcs_util.cpp.

Referenced by vcs_orderedUnique().

 void vcs_orderedUnique ( std::vector< int > & xOrderedUnique, const std::vector< int > & x )

Sorts a vector of ints and eliminates duplicates from the resulting list.

Parameters
 xOrderedUnique Ordered vector of unique ints that were part of the original list x Reference to a constant vector of ints.
Deprecated:

Definition at line 700 of file vcs_util.cpp.

References vcs_heapsort().

 std::string string16_EOSType ( int EOSType )

Return a string representing the equation of state.

Parameters
 EOSType : integer value of the equation of state
Returns
returns a string representing the EOS. The string is no more than 16 characters.

Definition at line 996 of file vcs_VolPhase.cpp.

Referenced by VCS_PROB::prob_report(), vcs_Cantera_to_vprob(), and vcs_Cantera_update_vprob().

 static bool VCSnonideal::hasChargedSpecies ( const Cantera::ThermoPhase *const tPhase )
static

This function decides whether a phase has charged species or not.

Definition at line 1174 of file vcs_VolPhase.cpp.

References Phase::charge(), and Phase::nSpecies().

Referenced by chargeNeutralityElement(), and vcs_VolPhase::transferElementsFM().

 static bool VCSnonideal::chargeNeutralityElement ( const Cantera::ThermoPhase *const tPhase )
static

This utility routine decides whether a Cantera ThermoPhase needs a constraint equation representing the charge neutrality of the phase. It does this by searching for charged species. If it finds one, and if the phase needs one, then it returns true.

Definition at line 1190 of file vcs_VolPhase.cpp.

References ThermoPhase::chargeNeutralityNecessary(), and hasChargedSpecies().

Referenced by vcs_VolPhase::transferElementsFM().

 double VCSnonideal::vcs_second ( )

Returns the system wall clock time in seconds.

Returns
time in seconds.
 void VCSnonideal::vcs_dzero ( double *const vec_to, const size_t length )
inline

Zero a double vector.

Parameters
 vec_to vector of doubles length length of the vector to zero.

Definition at line 310 of file vcs_internal.h.

 void VCSnonideal::vcs_izero ( int *const vec_to, const size_t length )
inline

Zero an int vector.

Parameters
 vec_to vector of ints length length of the vector to zero.

Definition at line 320 of file vcs_internal.h.

 void VCSnonideal::vcs_dcopy ( double *const vec_to, const double *const vec_from, const size_t length )
inline

Copy a double vector.

Parameters
 vec_to Vector to copy into. This vector must be dimensioned at least as large as the vec_from vector. vec_from Vector to copy from length Number of doubles to copy.

Definition at line 332 of file vcs_internal.h.

 void VCSnonideal::vcs_icopy ( int *const vec_to, const int *const vec_from, const size_t length )
inline

Copy an int vector.

Parameters
 vec_to Vector to copy into. This vector must be dimensioned at least as large as the vec_from vector. vec_from Vector to copy from length Number of int to copy.

Definition at line 346 of file vcs_internal.h.

 void VCSnonideal::vcs_vdzero ( std::vector< double > & vec_to, const size_t length )
inline

Zero a std double vector.

Parameters
 vec_to vector of doubles length length of the vector to zero.

Definition at line 358 of file vcs_internal.h.

References VCS_DATA_PTR.

 void VCSnonideal::vcs_vizero ( std::vector< int > & vec_to, const size_t length )
inline

Zero a std int vector.

Parameters
 vec_to vector of ints length length of the vector to zero.

Definition at line 368 of file vcs_internal.h.

References VCS_DATA_PTR.

 void VCSnonideal::vcs_vdcopy ( std::vector< double > & vec_to, const std::vector< double > & vec_from, size_t length )
inline

Copy one std double vector into another.

This is an inlined function that uses memcpy. memcpy is probably the fastest way to do this. This routine requires the vectors to be previously dimensioned appropriately. No error checking is done.

Parameters
 vec_to Vector to copy into. This vector must be dimensioned at least as large as the vec_from vector. vec_from Vector to copy from length Number of doubles to copy.

Definition at line 384 of file vcs_internal.h.

## Variable Documentation

 int vcs_timing_print_lvl = 1

Global hook for turning on and off time printing.

Default is to allow printing. But, you can assign this to zero globally to turn off all time printing. This is helpful for test suite purposes where you are interested in differences in text files.

Definition at line 27 of file vcs_solve.cpp.

Referenced by VCS_SOLVE::vcs_initSizes().