Cantera 2.6.0

Public Member Functions | Protected Member Functions | Protected Attributes | Private Attributes | Friends | List of all members
ImplicitSurfChem Class Reference
Chemical Kinetics » Kinetics Managers

Advances the surface coverages of the associated set of SurfacePhase objects in time. More...

`#include <ImplicitSurfChem.h>`

Inheritance diagram for ImplicitSurfChem:
[legend]
Collaboration diagram for ImplicitSurfChem:
[legend]

## Public Member Functions
| ImplicitSurfChem (std::vector< InterfaceKinetics * > k, double rtol=1.e-7, double atol=1.e-14, double maxStepSize=0, size_t maxSteps=20000, size_t maxErrTestFails=7)
| Constructor for multiple surfaces. More...
virtual void | initialize (doublereal t0=0.0)
virtual void | setMaxStepSize (double maxstep=0.0)
virtual void | setTolerances (double rtol=1.e-7, double atol=1.e-14)
virtual void | setMaxSteps (size_t maxsteps=20000)
virtual void | setMaxErrTestFails (size_t maxErrTestFails=7)
void | integrate (doublereal t0, doublereal t1)
| Integrate from t0 to t1. The integrator is reinitialized first. More...
void | integrate0 (doublereal t0, doublereal t1)
| Integrate from t0 to t1 without reinitializing the integrator. More...
void | solvePseudoSteadyStateProblem (int ifuncOverride=-1, doublereal timeScaleOverride=1.0)
| Solve for the pseudo steady-state of the surface problem. More...
virtual size_t | neq ()
| Return the number of equations. More...
virtual void | eval (doublereal t, doublereal *y, doublereal *ydot, doublereal *p)
| Evaluate the value of ydot[k] at the current conditions. More...
virtual void | getState (doublereal *y)
| Get the current state of the solution vector. More...
void | getConcSpecies (doublereal *const vecConcSpecies) const
void | setConcSpecies (const doublereal *const vecConcSpecies)
| Sets the concentrations within phases that are unknowns in the surface problem. More...
void | setCommonState_TP (doublereal TKelvin, doublereal PresPa)
| Sets the state variable in all thermodynamic phases (surface and surrounding bulk phases) to the input temperature and pressure. More...
std::vector< InterfaceKinetics * > & | getObjects ()
| Returns a reference to the vector of pointers to the InterfaceKinetics objects. More...
int | checkMatch (std::vector< ThermoPhase * > m_vec, ThermoPhase *thPtr)
void | setIOFlag (int ioFlag)
Public Member Functions inherited from FuncEval
virtual void | eval (double t, double *y, double *ydot, double *p)=0
| Evaluate the right-hand-side function. More...
int | eval_nothrow (double t, double *y, double *ydot)
| Evaluate the right-hand side using return code to indicate status. More...
virtual void | getState (double *y)
| Fill in the vector y with the current state of the system. More...
virtual size_t | neq ()=0
| Number of equations. More...
virtual size_t | nparams ()
| Number of sensitivity parameters. More...
void | suppressErrors (bool suppress)
| Enable or disable suppression of errors when calling eval() More...
bool | suppressErrors () const
| Get current state of error suppression. More...
std::string | getErrors () const
| Return a string containing the text of any suppressed errors. More...
void | clearErrors ()
| Clear any previously-stored suppressed errors. More...

## Protected Member Functions
void | updateState (doublereal *y)
| Set the mixture to a state consistent with solution vector y. More...

## Protected Attributes
std::vector< SurfPhase * > | m_surf
| vector of pointers to surface phases. More...
std::vector< ThermoPhase * > | m_bulkPhases
| Vector of pointers to bulk phases. More...
std::vector< InterfaceKinetics * > | m_vecKinPtrs
| vector of pointers to InterfaceKinetics objects More...
std::vector< size_t > | m_nsp
| Vector of number of species in each Surface Phase. More...
std::vector< size_t > | m_surfindex
| index of the surface phase in each InterfaceKinetics object More...
std::vector< size_t > | m_specStartIndex
size_t | m_nv
| Total number of surface species in all surface phases. More...
size_t | m_numTotalBulkSpecies
size_t | m_numTotalSpecies
std::vector< vector_int > | pLocVec
std::unique_ptr< Integrator > | m_integ
| Pointer to the CVODE integrator. More...
doublereal | m_atol
doublereal | m_rtol
doublereal | m_maxstep
| max step size More...
size_t | m_nmax
| maximum number of steps allowed More...
size_t | m_maxErrTestFails
| maximum number of error test failures allowed More...
vector_fp | m_work
vector_fp | m_concSpecies
| Temporary vector - length num species in the Kinetics object. More...
vector_fp | m_concSpeciesSave
int | m_mediumSpeciesStart
| Index into the species vector of the kinetics manager, pointing to the first species from the surrounding medium. More...
int | m_bulkSpeciesStart
| Index into the species vector of the kinetics manager, pointing to the first species from the condensed phase of the particles. More...
int | m_surfSpeciesStart
| Index into the species vector of the kinetics manager, pointing to the first species from the surface of the particles. More...
std::unique_ptr< solveSP > | m_surfSolver
| Pointer to the helper method, Placid, which solves the surface problem. More...
bool | m_commonTempPressForPhases
| If true, a common temperature and pressure for all surface and bulk phases associated with the surface problem is imposed. More...
Protected Attributes inherited from FuncEval
bool | m_suppress_errors
std::vector< std::string > | m_errors
| Errors occurring during function evaluations. More...

## Private Attributes
int | m_ioFlag
| Controls the amount of printing from this routine and underlying routines. More...

## Friends
class | solveSS
| We make the solveSS class a friend because we need to access all of the above information directly. More...

## Additional Inherited Members
Public Attributes inherited from FuncEval
vector_fp | m_sens_params
| Values for the problem parameters for which sensitivities are computed This is the array which is perturbed and passed back as the fourth argument to eval(). More...
vector_fp | m_paramScales
| Scaling factors for each sensitivity parameter. More...

## Detailed Description

Advances the surface coverages of the associated set of SurfacePhase objects in time.

This function advances a set of SurfPhase objects, each associated with one InterfaceKinetics object, in time. The following equation is used for each surface phase, i.

\[ \dot \theta_k = \dot s_k (\sigma_k / s_0) \]

In this equation,

- \( \theta_k \) is the site coverage for the kth species.
- \( \dot s_k \) is the source term for the kth species
- \( \sigma_k \) is the number of surface sites covered by each species k.
- \( s_0 \) is the total site density of the interfacial phase.

Additionally, the 0'th equation in the set is discarded. Instead the alternate equation is solved for

\[ \sum_{k=0}^{N-1} \dot \theta_k = 0 \]

This last equation serves to ensure that sum of the \( \theta_k \) values stays constant.

The object uses the CVODE software to advance the surface equations.

The solution vector used by this object is as follows: For each surface phase with \( N_s \) surface sites, it consists of the surface coverages \( \theta_k \) for \( k = 0, N_s - 1 \)

Definition at line 56 of file ImplicitSurfChem.h.

## Constructor & Destructor Documentation

## ◆ ImplicitSurfChem()

ImplicitSurfChem | ( | std::vector< InterfaceKinetics * > | k,
|  | double | rtol = `1.e-7`,
|  | double | atol = `1.e-14`,
|  | double | maxStepSize = `0`,
|  | size_t | maxSteps = `20000`,
|  | size_t | maxErrTestFails = `7`
| ) |  |

Constructor for multiple surfaces.

Parameters

  k | Vector of pointers to InterfaceKinetics objects Each object consists of a surface or an edge containing internal degrees of freedom representing the concentration of surface adsorbates.
  rtol | The relative tolerance for the integrator
  atol | The absolute tolerance for the integrator
  maxStepSize | The maximum step-size the integrator is allowed to take. If zero, this option is disabled.
  maxSteps | The maximum number of time-steps the integrator can take. If not supplied, uses the default value in the CVodesIntegrator (20000).
  maxErrTestFails | the maximum permissible number of error test failures If not supplied, uses the default value in CVODES (7).

Definition at line 20 of file ImplicitSurfChem.cpp.

## ◆ ~ImplicitSurfChem()

virtual ~ImplicitSurfChem | ( |  | ) |
| inline virtual

Definition at line 78 of file ImplicitSurfChem.h.

## Member Function Documentation

## ◆ initialize()

void initialize | ( | doublereal | t0 = `0.0` | ) |
| virtual

Must be called before calling method 'advance'

Definition at line 138 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ, ImplicitSurfChem::m_maxErrTestFails, ImplicitSurfChem::m_maxstep, ImplicitSurfChem::m_nmax, ImplicitSurfChem::setMaxErrTestFails(), ImplicitSurfChem::setMaxSteps(), ImplicitSurfChem::setMaxStepSize(), and ImplicitSurfChem::setTolerances().

Referenced by ImplicitSurfChem::integrate(), and InterfaceKinetics::solvePseudoSteadyStateProblem().

## ◆ setMaxStepSize()

void setMaxStepSize | ( | double | maxstep = `0.0` | ) |
| virtual

Set the maximum integration step-size. Note, setting this value to zero disables this option

Definition at line 111 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ, and ImplicitSurfChem::m_maxstep.

Referenced by InterfaceKinetics::advanceCoverages(), and ImplicitSurfChem::initialize().

## ◆ setTolerances()

void setTolerances | ( | double | rtol = `1.e-7`,
|  | double | atol = `1.e-14`
| ) |  |
| virtual

Set the relative and absolute integration tolerances.

Definition at line 119 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ.

Referenced by InterfaceKinetics::advanceCoverages(), and ImplicitSurfChem::initialize().

## ◆ setMaxSteps()

void setMaxSteps | ( | size_t | maxsteps = `20000` | ) |
| virtual

Set the maximum number of CVODES integration steps.

Definition at line 126 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ, and ImplicitSurfChem::m_nmax.

Referenced by InterfaceKinetics::advanceCoverages(), and ImplicitSurfChem::initialize().

## ◆ setMaxErrTestFails()

void setMaxErrTestFails | ( | size_t | maxErrTestFails = `7` | ) |
| virtual

Set the maximum number of CVODES error test failures

Definition at line 132 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ, and ImplicitSurfChem::m_maxErrTestFails.

Referenced by InterfaceKinetics::advanceCoverages(), and ImplicitSurfChem::initialize().

## ◆ integrate()

void integrate | ( | doublereal | t0,
|  | doublereal | t1
| ) |  |

Integrate from t0 to t1. The integrator is reinitialized first.

This routine does a time accurate solve from t = t0 to t = t1. of the surface problem.

Parameters

  t0 | Initial Time -> this is an input
  t1 | Final Time -> This is an input

Definition at line 147 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::initialize(), ImplicitSurfChem::m_integ, ImplicitSurfChem::m_maxstep, and ImplicitSurfChem::updateState().

Referenced by InterfaceKinetics::advanceCoverages().

## ◆ integrate0()

void integrate0 | ( | doublereal | t0,
|  | doublereal | t1
| ) |  |

Integrate from t0 to t1 without reinitializing the integrator.

Use when the coverages have not changed from their values on return from the last call to integrate or integrate0.

Parameters

  t0 | Initial Time -> this is an input
  t1 | Final Time -> This is an input

Definition at line 158 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_integ, and ImplicitSurfChem::updateState().

## ◆ solvePseudoSteadyStateProblem()

void solvePseudoSteadyStateProblem | ( | int | ifuncOverride = `-1`,
|  | doublereal | timeScaleOverride = `1.0`
| ) |  |

Solve for the pseudo steady-state of the surface problem.

Solve for the steady state of the surface problem. This is the same thing as the advanceCoverages() function, but at infinite times.

Note, a direct solve is carried out under the hood here, to reduce the computational time.

Parameters

  ifuncOverride | One of the values defined in Surface Problem Solver Methods. The default is -1, which means that the program will decide.
  timeScaleOverride | When a pseudo transient is selected this value can be used to override the default time scale for integration which is one. When SFLUX_TRANSIENT is used, this is equal to the time over which the equations are integrated. When SFLUX_INITIALIZE is used, this is equal to the time used in the initial transient algorithm, before the equation system is solved directly.

Definition at line 192 of file ImplicitSurfChem.cpp.

References BULK_ETCH, ImplicitSurfChem::getConcSpecies(), ImplicitSurfChem::m_commonTempPressForPhases, ImplicitSurfChem::m_concSpecies, ImplicitSurfChem::m_ioFlag, ImplicitSurfChem::m_nv, ImplicitSurfChem::m_surfSolver, ImplicitSurfChem::m_vecKinPtrs, Phase::pressure(), Kinetics::reactionPhaseIndex(), ImplicitSurfChem::setCommonState_TP(), ImplicitSurfChem::setConcSpecies(), SFLUX_INITIALIZE, SFLUX_RESIDUAL, Phase::temperature(), and Kinetics::thermo().

Referenced by InterfaceKinetics::solvePseudoSteadyStateProblem().

## ◆ neq()

virtual size_t neq | ( |  | ) |
| inline virtual

Return the number of equations.

Implements FuncEval.

Definition at line 151 of file ImplicitSurfChem.h.

References ImplicitSurfChem::m_nv.

## ◆ eval()

void eval | ( | doublereal | t,
|  | doublereal * | y,
|  | doublereal * | ydot,
|  | doublereal * | p
| ) |  |
| virtual

Evaluate the value of ydot[k] at the current conditions.

Parameters

  t | Time (seconds)
  y | Vector containing the current solution vector
  ydot | Output vector containing the value of the derivative of the surface coverages.
  p | Unused parameter pass-through parameter vector

Implements FuncEval.

Definition at line 173 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_nsp, ImplicitSurfChem::m_surf, ImplicitSurfChem::m_surfindex, ImplicitSurfChem::m_vecKinPtrs, and ImplicitSurfChem::updateState().

## ◆ getState()

void getState | ( | doublereal * | y | ) |
| virtual

Get the current state of the solution vector.

Parameters

  y | Value of the solution vector to be used. On output, this contains the initial value of the solution.

Reimplemented from FuncEval.

Definition at line 102 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_nsp, and ImplicitSurfChem::m_surf.

## ◆ getConcSpecies()

void getConcSpecies | ( | doublereal *const | vecConcSpecies | ) | const

Get the specifications for the problem from the values in the ThermoPhase objects for all phases.

1. concentrations of all species in all phases, m_concSpecies
2. Temperature and pressure

Parameters

  vecConcSpecies | Vector of concentrations. The phase concentration vectors are contiguous within the object, in the same order as the unknown vector.

Definition at line 268 of file ImplicitSurfChem.cpp.

References Phase::getConcentrations(), ImplicitSurfChem::m_bulkPhases, ImplicitSurfChem::m_nv, ImplicitSurfChem::m_surf, and Phase::nSpecies().

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ setConcSpecies()

void setConcSpecies | ( | const doublereal *const | vecConcSpecies | ) |

Sets the concentrations within phases that are unknowns in the surface problem.

Fills the local concentration vector for all of the species in all of the phases that are unknowns in the surface problem.

Parameters

  vecConcSpecies | Vector of concentrations. The phase concentration vectors are contiguous within the object, in the same order as the unknown vector.

Definition at line 284 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_bulkPhases, ImplicitSurfChem::m_nv, ImplicitSurfChem::m_surf, Phase::nSpecies(), and Phase::setConcentrations().

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ setCommonState_TP()

void setCommonState_TP | ( | doublereal | TKelvin,
|  | doublereal | PresPa
| ) |  |

Sets the state variable in all thermodynamic phases (surface and surrounding bulk phases) to the input temperature and pressure.

Parameters

  TKelvin | input temperature (kelvin)
  PresPa | input pressure in pascal.

Definition at line 300 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_bulkPhases, ImplicitSurfChem::m_surf, and ThermoPhase::setState_TP().

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ getObjects()

std::vector< InterfaceKinetics * > & getObjects | ( |  | ) |
| inline

Returns a reference to the vector of pointers to the InterfaceKinetics objects.

This should probably go away in the future, as it opens up the class.

Definition at line 212 of file ImplicitSurfChem.h.

References ImplicitSurfChem::m_vecKinPtrs.

## ◆ checkMatch()

int checkMatch | ( | std::vector< ThermoPhase * > | m_vec,
|  | ThermoPhase * | thPtr
| ) |  |

Definition at line 90 of file ImplicitSurfChem.cpp.

## ◆ setIOFlag()

void setIOFlag | ( | int | ioFlag | ) |
| inline

Definition at line 218 of file ImplicitSurfChem.h.

## ◆ updateState()

void updateState | ( | doublereal * | y | ) |
| protected

Set the mixture to a state consistent with solution vector y.

This function will set the surface site factions in the underlying SurfPhase objects to the current value of the solution vector.

Parameters

  y | Current value of the solution vector. The length is equal to the sum of the number of surface sites in all the surface phases.

Definition at line 164 of file ImplicitSurfChem.cpp.

References ImplicitSurfChem::m_nsp, and ImplicitSurfChem::m_surf.

Referenced by ImplicitSurfChem::eval(), ImplicitSurfChem::integrate(), and ImplicitSurfChem::integrate0().

## Friends And Related Function Documentation

## ◆ solveSS

friend class solveSS
| friend

We make the solveSS class a friend because we need to access all of the above information directly.

Adding the members into the class is also a possibility.

Definition at line 304 of file ImplicitSurfChem.h.

## Member Data Documentation

## ◆ m_surf

std::vector<SurfPhase*> m_surf
| protected

vector of pointers to surface phases.

Definition at line 235 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::eval(), ImplicitSurfChem::getConcSpecies(), ImplicitSurfChem::getState(), ImplicitSurfChem::setCommonState_TP(), ImplicitSurfChem::setConcSpecies(), and ImplicitSurfChem::updateState().

## ◆ m_bulkPhases

std::vector<ThermoPhase*> m_bulkPhases
| protected

Vector of pointers to bulk phases.

Definition at line 238 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::getConcSpecies(), ImplicitSurfChem::setCommonState_TP(), and ImplicitSurfChem::setConcSpecies().

## ◆ m_vecKinPtrs

std::vector<InterfaceKinetics*> m_vecKinPtrs
| protected

vector of pointers to InterfaceKinetics objects

Definition at line 241 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::eval(), ImplicitSurfChem::getObjects(), and ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ m_nsp

std::vector<size_t> m_nsp
| protected

Vector of number of species in each Surface Phase.

Definition at line 244 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::eval(), ImplicitSurfChem::getState(), and ImplicitSurfChem::updateState().

## ◆ m_surfindex

std::vector<size_t> m_surfindex
| protected

index of the surface phase in each InterfaceKinetics object

Definition at line 247 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::eval().

## ◆ m_specStartIndex

std::vector<size_t> m_specStartIndex
| protected

Definition at line 249 of file ImplicitSurfChem.h.

## ◆ m_nv

size_t m_nv
| protected

Total number of surface species in all surface phases.

This is the total number of unknowns in m_mode 0 problem

Definition at line 255 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::getConcSpecies(), ImplicitSurfChem::neq(), ImplicitSurfChem::setConcSpecies(), and ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ m_numTotalBulkSpecies

size_t m_numTotalBulkSpecies
| protected

Definition at line 257 of file ImplicitSurfChem.h.

## ◆ m_numTotalSpecies

size_t m_numTotalSpecies
| protected

Definition at line 258 of file ImplicitSurfChem.h.

## ◆ pLocVec

std::vector<vector_int> pLocVec
| protected

Definition at line 260 of file ImplicitSurfChem.h.

## ◆ m_integ

std::unique_ptr<Integrator> m_integ
| protected

Pointer to the CVODE integrator.

Definition at line 262 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::initialize(), ImplicitSurfChem::integrate(), ImplicitSurfChem::integrate0(), ImplicitSurfChem::setMaxErrTestFails(), ImplicitSurfChem::setMaxSteps(), ImplicitSurfChem::setMaxStepSize(), and ImplicitSurfChem::setTolerances().

## ◆ m_atol

doublereal m_atol
| protected

Definition at line 263 of file ImplicitSurfChem.h.

## ◆ m_rtol

doublereal m_rtol
| protected

Definition at line 263 of file ImplicitSurfChem.h.

## ◆ m_maxstep

doublereal m_maxstep
| protected

max step size

Definition at line 264 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::initialize(), ImplicitSurfChem::integrate(), and ImplicitSurfChem::setMaxStepSize().

## ◆ m_nmax

size_t m_nmax
| protected

maximum number of steps allowed

Definition at line 265 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::initialize(), and ImplicitSurfChem::setMaxSteps().

## ◆ m_maxErrTestFails

size_t m_maxErrTestFails
| protected

maximum number of error test failures allowed

Definition at line 266 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::initialize(), and ImplicitSurfChem::setMaxErrTestFails().

## ◆ m_work

vector_fp m_work
| protected

Definition at line 267 of file ImplicitSurfChem.h.

## ◆ m_concSpecies

vector_fp m_concSpecies
| protected

Temporary vector - length num species in the Kinetics object.

This is the sum of the number of species in each phase included in the kinetics object.

Definition at line 274 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ m_concSpeciesSave

vector_fp m_concSpeciesSave
| protected

Definition at line 275 of file ImplicitSurfChem.h.

## ◆ m_mediumSpeciesStart

int m_mediumSpeciesStart
| protected

Index into the species vector of the kinetics manager, pointing to the first species from the surrounding medium.

Definition at line 281 of file ImplicitSurfChem.h.

## ◆ m_bulkSpeciesStart

int m_bulkSpeciesStart
| protected

Index into the species vector of the kinetics manager, pointing to the first species from the condensed phase of the particles.

Definition at line 286 of file ImplicitSurfChem.h.

## ◆ m_surfSpeciesStart

int m_surfSpeciesStart
| protected

Index into the species vector of the kinetics manager, pointing to the first species from the surface of the particles.

Definition at line 291 of file ImplicitSurfChem.h.

## ◆ m_surfSolver

std::unique_ptr<solveSP> m_surfSolver
| protected

Pointer to the helper method, Placid, which solves the surface problem.

Definition at line 295 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ m_commonTempPressForPhases

bool m_commonTempPressForPhases
| protected

If true, a common temperature and pressure for all surface and bulk phases associated with the surface problem is imposed.

Definition at line 299 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

## ◆ m_ioFlag

int m_ioFlag
| private

Controls the amount of printing from this routine and underlying routines.

Definition at line 309 of file ImplicitSurfChem.h.

Referenced by ImplicitSurfChem::solvePseudoSteadyStateProblem().

The documentation for this class was generated from the following files:

- ImplicitSurfChem.h
- ImplicitSurfChem.cpp