Cantera  2.4.0
ImplicitSurfChem.h
Go to the documentation of this file.
1 /**
2  * @file ImplicitSurfChem.h
3  * Declarations for the implicit integration of surface site density equations
4  * (see \ref kineticsmgr and class
5  * \link Cantera::ImplicitSurfChem ImplicitSurfChem\endlink).
6  */
7 
8 // This file is part of Cantera. See License.txt in the top-level directory or
9 // at http://www.cantera.org/license.txt for license and copyright information.
10 
11 #ifndef CT_IMPSURFCHEM_H
12 #define CT_IMPSURFCHEM_H
13 
17 
18 namespace Cantera
19 {
20 
21 //! Advances the surface coverages of the associated set of SurfacePhase
22 //! objects in time
23 /*!
24  * This function advances a set of SurfPhase objects, each associated with one
25  * InterfaceKinetics object, in time. The following equation is used for each
26  * surface phase, *i*.
27  *
28  * \f[
29  * \dot \theta_k = \dot s_k (\sigma_k / s_0)
30  * \f]
31  *
32  * In this equation,
33  * - \f$ \theta_k \f$ is the site coverage for the kth species.
34  * - \f$ \dot s_k \f$ is the source term for the kth species
35  * - \f$ \sigma_k \f$ is the number of surface sites covered by each species k.
36  * - \f$ s_0 \f$ is the total site density of the interfacial phase.
37  *
38  * Additionally, the 0'th equation in the set is discarded. Instead the
39  * alternate equation is solved for
40  *
41  * \f[
42  * \sum_{k=0}^{N-1} \dot \theta_k = 0
43  * \f]
44  *
45  * This last equation serves to ensure that sum of the \f$ \theta_k \f$ values
46  * stays constant.
47  *
48  * The object uses the CVODE software to advance the surface equations.
49  *
50  * The solution vector used by this object is as follows: For each surface
51  * phase with \f$ N_s \f$ surface sites, it consists of the surface coverages
52  * \f$ \theta_k \f$ for \f$ k = 0, N_s - 1 \f$
53  *
54  * @ingroup kineticsmgr
55  */
56 class ImplicitSurfChem : public FuncEval
57 {
58 public:
59  //! Constructor for multiple surfaces.
60  /*!
61  * @param k Vector of pointers to InterfaceKinetics objects Each object
62  * consists of a surface or an edge containing internal degrees of
63  * freedom representing the concentration of surface adsorbates.
64  */
65  ImplicitSurfChem(std::vector<InterfaceKinetics*> k);
66 
67  virtual ~ImplicitSurfChem() {};
68 
69  /*!
70  * Must be called before calling method 'advance'
71  */
72  virtual void initialize(doublereal t0 = 0.0);
73 
74  //! Integrate from t0 to t1. The integrator is reinitialized first.
75  /*!
76  * This routine does a time accurate solve from t = t0 to t = t1.
77  * of the surface problem.
78  *
79  * @param t0 Initial Time -> this is an input
80  * @param t1 Final Time -> This is an input
81  */
82  void integrate(doublereal t0, doublereal t1);
83 
84  //! Integrate from t0 to t1 without reinitializing the integrator.
85  /*!
86  * Use when the coverages have not changed from their values on return
87  * from the last call to integrate or integrate0.
88  *
89  * @param t0 Initial Time -> this is an input
90  * @param t1 Final Time -> This is an input
91  */
92  void integrate0(doublereal t0, doublereal t1);
93 
94  //! Solve for the pseudo steady-state of the surface problem
95  /*!
96  * Solve for the steady state of the surface problem.
97  * This is the same thing as the advanceCoverages() function,
98  * but at infinite times.
99  *
100  * Note, a direct solve is carried out under the hood here,
101  * to reduce the computational time.
102  *
103  * @param ifuncOverride One of the values defined in @ref solvesp_methods.
104  * The default is -1, which means that the program will decide.
105  * @param timeScaleOverride When a pseudo transient is selected this value
106  * can be used to override the default time scale for
107  * integration which is one. When SFLUX_TRANSIENT is used, this
108  * is equal to the time over which the equations are integrated.
109  * When SFLUX_INITIALIZE is used, this is equal to the time used
110  * in the initial transient algorithm, before the equation
111  * system is solved directly.
112  */
113  void solvePseudoSteadyStateProblem(int ifuncOverride = -1,
114  doublereal timeScaleOverride = 1.0);
115 
116  // overloaded methods of class FuncEval
117 
118  //! Return the number of equations
119  virtual size_t neq() {
120  return m_nv;
121  }
122 
123  //! Evaluate the value of ydot[k] at the current conditions
124  /*!
125  * @param t Time (seconds)
126  * @param y Vector containing the current solution vector
127  * @param ydot Output vector containing the value of the
128  * derivative of the surface coverages.
129  * @param p Unused parameter pass-through parameter vector
130  */
131  virtual void eval(doublereal t, doublereal* y, doublereal* ydot,
132  doublereal* p);
133 
134  //! Get the current state of the solution vector
135  /*!
136  * @param y Value of the solution vector to be used.
137  * On output, this contains the initial value
138  * of the solution.
139  */
140  virtual void getState(doublereal* y);
141 
142  /*!
143  * Get the specifications for the problem from the values
144  * in the ThermoPhase objects for all phases.
145  *
146  * 1. concentrations of all species in all phases, #m_concSpecies
147  * 2. Temperature and pressure
148  *
149  * @param vecConcSpecies Vector of concentrations. The phase concentration
150  * vectors are contiguous within the object, in the same
151  * order as the unknown vector.
152  */
153  void getConcSpecies(doublereal* const vecConcSpecies) const;
154 
155  //! Sets the concentrations within phases that are unknowns in
156  //! the surface problem
157  /*!
158  * Fills the local concentration vector for all of the species in all of
159  * the phases that are unknowns in the surface problem.
160  *
161  * @param vecConcSpecies Vector of concentrations. The phase concentration
162  * vectors are contiguous within the object, in the same
163  * order as the unknown vector.
164  */
165  void setConcSpecies(const doublereal* const vecConcSpecies);
166 
167  //! Sets the state variable in all thermodynamic phases (surface and
168  //! surrounding bulk phases) to the input temperature and pressure
169  /*!
170  * @param TKelvin input temperature (kelvin)
171  * @param PresPa input pressure in pascal.
172  */
173  void setCommonState_TP(doublereal TKelvin, doublereal PresPa);
174 
175  //! Returns a reference to the vector of pointers to the
176  //! InterfaceKinetics objects
177  /*!
178  * This should probably go away in the future, as it opens up the class.
179  */
180  std::vector<InterfaceKinetics*> & getObjects() {
181  return m_vecKinPtrs;
182  }
183 
184  int checkMatch(std::vector<ThermoPhase*> m_vec, ThermoPhase* thPtr);
185 
186  void setIOFlag(int ioFlag) {
187  m_ioFlag = ioFlag;
188  }
189 
190 protected:
191  //! Set the mixture to a state consistent with solution
192  //! vector y.
193  /*!
194  * This function will set the surface site factions in the underlying
195  * SurfPhase objects to the current value of the solution vector.
196  *
197  * @param y Current value of the solution vector. The lenth is equal to
198  * the sum of the number of surface sites in all the surface phases.
199  */
200  void updateState(doublereal* y);
201 
202  //! vector of pointers to surface phases.
203  std::vector<SurfPhase*> m_surf;
204 
205  //! Vector of pointers to bulk phases
206  std::vector<ThermoPhase*> m_bulkPhases;
207 
208  //! vector of pointers to InterfaceKinetics objects
209  std::vector<InterfaceKinetics*> m_vecKinPtrs;
210 
211  //! Vector of number of species in each Surface Phase
212  std::vector<size_t> m_nsp;
213 
214  //! index of the surface phase in each InterfaceKinetics object
215  std::vector<size_t> m_surfindex;
216 
217  std::vector<size_t> m_specStartIndex;
218 
219  //! Total number of surface species in all surface phases
220  /*!
221  * This is the total number of unknowns in m_mode 0 problem
222  */
223  size_t m_nv;
224 
225  size_t m_numTotalBulkSpecies;
226  size_t m_numTotalSpecies;
227 
228  std::vector<vector_int> pLocVec;
229  //! Pointer to the CVODE integrator
230  std::unique_ptr<Integrator> m_integ;
231  doublereal m_atol, m_rtol; // tolerances
232  doublereal m_maxstep; //!< max step size
233  vector_fp m_work;
234 
235  /**
236  * Temporary vector - length num species in the Kinetics object. This is
237  * the sum of the number of species in each phase included in the kinetics
238  * object.
239  */
241  vector_fp m_concSpeciesSave;
242 
243  /**
244  * Index into the species vector of the kinetics manager,
245  * pointing to the first species from the surrounding medium.
246  */
248  /**
249  * Index into the species vector of the kinetics manager, pointing to the
250  * first species from the condensed phase of the particles.
251  */
253  /**
254  * Index into the species vector of the kinetics manager, pointing to the
255  * first species from the surface of the particles
256  */
258  /**
259  * Pointer to the helper method, Placid, which solves the surface problem.
260  */
261  std::unique_ptr<solveSP> m_surfSolver;
262 
263  //! If true, a common temperature and pressure for all surface and bulk
264  //! phases associated with the surface problem is imposed
266 
267  //! We make the solveSS class a friend because we need to access all of
268  //! the above information directly. Adding the members into the class is
269  //! also a possibility.
270  friend class solveSS;
271 
272 private:
273  //! Controls the amount of printing from this routine
274  //! and underlying routines.
275  int m_ioFlag;
276 };
277 }
278 
279 #endif
std::vector< size_t > m_surfindex
index of the surface phase in each InterfaceKinetics object
int m_mediumSpeciesStart
Index into the species vector of the kinetics manager, pointing to the first species from the surroun...
virtual void getState(doublereal *y)
Get the current state of the solution vector.
std::unique_ptr< Integrator > m_integ
Pointer to the CVODE integrator.
void solvePseudoSteadyStateProblem(int ifuncOverride=-1, doublereal timeScaleOverride=1.0)
Solve for the pseudo steady-state of the surface problem.
std::vector< ThermoPhase * > m_bulkPhases
Vector of pointers to bulk phases.
std::unique_ptr< solveSP > m_surfSolver
Pointer to the helper method, Placid, which solves the surface problem.
doublereal m_maxstep
max step size
std::vector< size_t > m_nsp
Vector of number of species in each Surface Phase.
friend class solveSS
We make the solveSS class a friend because we need to access all of the above information directly...
int m_surfSpeciesStart
Index into the species vector of the kinetics manager, pointing to the first species from the surface...
virtual size_t neq()
Return the number of equations.
std::vector< SurfPhase * > m_surf
vector of pointers to surface phases.
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:93
ImplicitSurfChem(std::vector< InterfaceKinetics *> k)
Constructor for multiple surfaces.
int m_ioFlag
Controls the amount of printing from this routine and underlying routines.
int m_bulkSpeciesStart
Index into the species vector of the kinetics manager, pointing to the first species from the condens...
bool m_commonTempPressForPhases
If true, a common temperature and pressure for all surface and bulk phases associated with the surfac...
size_t m_nv
Total number of surface species in all surface phases.
virtual void eval(doublereal t, doublereal *y, doublereal *ydot, doublereal *p)
Evaluate the value of ydot[k] at the current conditions.
void integrate0(doublereal t0, doublereal t1)
Integrate from t0 to t1 without reinitializing the integrator.
void setConcSpecies(const doublereal *const vecConcSpecies)
Sets the concentrations within phases that are unknowns in the surface problem.
std::vector< InterfaceKinetics * > & getObjects()
Returns a reference to the vector of pointers to the InterfaceKinetics objects.
void getConcSpecies(doublereal *const vecConcSpecies) const
Advances the surface coverages of the associated set of SurfacePhase objects in time.
virtual void initialize(doublereal t0=0.0)
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:157
void setCommonState_TP(doublereal TKelvin, doublereal PresPa)
Sets the state variable in all thermodynamic phases (surface and surrounding bulk phases) to the inpu...
void updateState(doublereal *y)
Set the mixture to a state consistent with solution vector y.
Header file for implicit surface problem solver (see Chemical Kinetics and class solveSP).
std::vector< InterfaceKinetics * > m_vecKinPtrs
vector of pointers to InterfaceKinetics objects
Virtual base class for ODE right-hand-side function evaluators.
Definition: FuncEval.h:26
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:8
vector_fp m_concSpecies
Temporary vector - length num species in the Kinetics object.
void integrate(doublereal t0, doublereal t1)
Integrate from t0 to t1. The integrator is reinitialized first.