Cantera/Surface Coverage - Revision history

Admin: Fix math formatting: remove unnecessary newlines inside $tags (same fix as parent page) (via update-page on MediaWiki MCP Server)$

2026-06-14T23:03:06Z

Fix math formatting: remove unnecessary newlines inside <math> tags (same fix as parent page) (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 23:03, 14 June 2026
Line 5:		Line 5:
	The heterogeneous reaction depends on a number of "moles" of solid species. The number of "moles" of solid species A is the product of the surface coverage (i.e., the "mole fraction") and the site density (i.e., the "total moles"):		The heterogeneous reaction depends on a number of "moles" of solid species. The number of "moles" of solid species A is the product of the surface coverage (i.e., the "mole fraction") and the site density (i.e., the "total moles"):

	<math>		<math>N_{A} = \theta_{A} \varrho</math>
	N_{A} = \theta_{A} \varrho
	</math>

	where <math>N_{A}</math> is the total "moles" of solid species A, <math>\theta_{A}</math> is the coverage of species A, and <math>\varrho</math> is the site density of the solid.		where <math>N_{A}</math> is the total "moles" of solid species A, <math>\theta_{A}</math> is the coverage of species A, and <math>\varrho</math> is the site density of the solid.

Admin at 00:27, 31 January 2014

2014-01-31T00:27:06Z

← Older revision		Revision as of 00:27, 31 January 2014
Line 1:		Line 1:
	In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.		In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.

			For information on surface reactions, see [[Cantera/Surface Reactions]]

	The heterogeneous reaction depends on a number of "moles" of solid species. The number of "moles" of solid species A is the product of the surface coverage (i.e., the "mole fraction") and the site density (i.e., the "total moles"):		The heterogeneous reaction depends on a number of "moles" of solid species. The number of "moles" of solid species A is the product of the surface coverage (i.e., the "mole fraction") and the site density (i.e., the "total moles"):

Admin at 00:58, 11 January 2014

2014-01-11T00:58:49Z

← Older revision		Revision as of 00:58, 11 January 2014
Line 31:		Line 31:
	Starting from the Reactor class, we see in the <code>getInitialConditions</code> method that we're looping over each Wall object associated with the Reactor, and we set the surface coverages for the wall.		Starting from the Reactor class, we see in the <code>getInitialConditions</code> method that we're looping over each Wall object associated with the Reactor, and we set the surface coverages for the wall.

	<source>		<source lang="cpp">
	// set the first component to the total internal		// set the first component to the total internal
	// energy		// energy
Line 62:		Line 62:
	The <code>Wall::getCoverages</code> method is not particularly interesting: it just copies data from one array into another.		The <code>Wall::getCoverages</code> method is not particularly interesting: it just copies data from one array into another.

	<source>		<source lang="cpp">
	void Wall::getCoverages(int leftright, doublereal* cov)		void Wall::getCoverages(int leftright, doublereal* cov)
	{		{
Line 87:		Line 87:
	The Reactor class's <code>updateState</code> method updates the Wall's surface coverages. In the file <code>Reactor.cpp</code>, the Reactor sets the coverages in the following code block:		The Reactor class's <code>updateState</code> method updates the Wall's surface coverages. In the file <code>Reactor.cpp</code>, the Reactor sets the coverages in the following code block:

	<source>		<source lang="cpp">
	size_t loc = m_nsp + 2;		size_t loc = m_nsp + 2;
	SurfPhase* surf;		SurfPhase* surf;
Line 105:		Line 105:
	In the Wall class, the setCoverages method is not doing anything too fancy. It's basically setting the contents of the Wall's coverage arrays (<code>m_leftcov</code> or <code>m_rightcov</code>) equal to the contents of another array (<code>cov</code>):		In the Wall class, the setCoverages method is not doing anything too fancy. It's basically setting the contents of the Wall's coverage arrays (<code>m_leftcov</code> or <code>m_rightcov</code>) equal to the contents of another array (<code>cov</code>):

	<source>		<source lang="cpp">
	void Wall::setCoverages(int leftright, const doublereal* cov)		void Wall::setCoverages(int leftright, const doublereal* cov)
	{		{
Line 127:		Line 127:
	\|content =		\|content =

	<source>		<source lang="cpp">
	// compute wall terms		// compute wall terms
	size_t loc = m_nsp+2;		size_t loc = m_nsp+2;
Line 170:		Line 170:
	The code first loops over each wall, checking if there is a surface phase associated with each wall, and if there is a reaction network on that surface (this happens via calls to the kinetics() and surface() methods of the Wall class):		The code first loops over each wall, checking if there is a surface phase associated with each wall, and if there is a reaction network on that surface (this happens via calls to the kinetics() and surface() methods of the Wall class):

	<source>		<source lang="cpp">
	for (size_t i = 0; i < m_nwalls; i++) {		for (size_t i = 0; i < m_nwalls; i++) {
	int lr = 1 - 2*m_lr[i];		int lr = 1 - 2*m_lr[i];
Line 188:		Line 188:
	If there is a surface with kinetics, the first thing that's done is to store the inverse site density and number of species, for assembling the RHS of the species coverage equation (the second of the two steps here):		If there is a surface with kinetics, the first thing that's done is to store the inverse site density and number of species, for assembling the RHS of the species coverage equation (the second of the two steps here):

	<source>		<source lang="cpp">
	if (surf && kin) {		if (surf && kin) {
	double rs0 = 1.0/surf->siteDensity();		double rs0 = 1.0/surf->siteDensity();
Line 197:		Line 197:
	Next, we set the surface temperature; we sync our coverages (more on this in a moment); and we get our net production rates from the surface kinetics:		Next, we set the surface temperature; we sync our coverages (more on this in a moment); and we get our net production rates from the surface kinetics:

	<source>		<source lang="cpp">
	surf->setTemperature(m_state[0]);		surf->setTemperature(m_state[0]);
	m_wall[i]->syncCoverages(m_lr[i]);		m_wall[i]->syncCoverages(m_lr[i]);
Line 205:		Line 205:
	The Wall class's syncCoverages method sets the coverages in the SurfPhase object (which Wall wraps). As with the get and set methods, this is simply the Wall object wrapping the SurfPhase object such that memory is managed properly. From the Wall class:		The Wall class's syncCoverages method sets the coverages in the SurfPhase object (which Wall wraps). As with the get and set methods, this is simply the Wall object wrapping the SurfPhase object such that memory is managed properly. From the Wall class:

	<source>		<source lang="cpp">
	void Wall::syncCoverages(int leftright)		void Wall::syncCoverages(int leftright)
	{		{
Line 220:		Line 220:
	From the InterfaceKinetics.cpp class:		From the InterfaceKinetics.cpp class:

	<source>		<source lang="cpp">
	void InterfaceKinetics::getNetProductionRates(doublereal* net)		void InterfaceKinetics::getNetProductionRates(doublereal* net)
	{		{
Line 236:		Line 236:
	The RHS for the surface coverage equation is a net reaction rate (not a volumetric reaction rate); it is found by multiplying the surface production rate, the inverse site density, and the number of surface sites occupied by species k (that's what <code>surf->size(k)</code> computes; see documentation for the <code>SurfPhase::setCoverages()</code> method):		The RHS for the surface coverage equation is a net reaction rate (not a volumetric reaction rate); it is found by multiplying the surface production rate, the inverse site density, and the number of surface sites occupied by species k (that's what <code>surf->size(k)</code> computes; see documentation for the <code>SurfPhase::setCoverages()</code> method):

	<source>		<source lang="cpp">
	size_t ns = kin->surfacePhaseIndex();		size_t ns = kin->surfacePhaseIndex();
	size_t surfloc = kin->kineticsSpeciesIndex(0,ns);		size_t surfloc = kin->kineticsSpeciesIndex(0,ns);

Admin: /* Overview of Class Hierarchy */

2014-01-10T23:43:54Z

Overview of Class Hierarchy

← Older revision		Revision as of 23:43, 10 January 2014
Line 23:		Line 23:
	* Set coverages - once the new coverages are calculated, they need to be set.		* Set coverages - once the new coverages are calculated, they need to be set.

	This page covers the [[#Calculating Coverages]], [[#~~Get~~ Coverages]], and [[#~~Set~~ Coverages]] methods below.		This page covers the [[#Calculating Coverages]], [[#Getting Coverages]], and [[#Setting Coverages]] methods below.

	=Getting Coverages=		=Getting Coverages=

Admin: moved Cantera surface coverage to Cantera/Surface Coverage

2014-01-10T23:39:05Z

moved Cantera surface coverage to Cantera/Surface Coverage

← Older revision	Revision as of 23:39, 10 January 2014
(No difference)

Admin at 19:14, 9 January 2014

2014-01-09T19:14:14Z

← Older revision		Revision as of 19:14, 9 January 2014
Line 248:		Line 248:

	This allows us to compute RHS for surface coverage ODEs, which goes into the sum variable.		This allows us to compute RHS for surface coverage ODEs, which goes into the sum variable.

			[[Category:Cantera]]

Admin: /* Calculating Coverages */

2014-01-09T19:13:17Z

Calculating Coverages

← Older revision		Revision as of 19:13, 9 January 2014
Line 119:		Line 119:

	More interesting than getting or setting coverages, is calculating coverages.		More interesting than getting or setting coverages, is calculating coverages.

			==Reactor::evalEqs()==

	The money shot is in the <code>Reactor::evalEqs</code> method, which computes the wall terms for the Reactor:		The money shot is in the <code>Reactor::evalEqs</code> method, which computes the wall terms for the Reactor:

			{{Scroll box
			\|content =

	<source>		<source>
Line 157:		Line 162:

	</source>		</source>
			}}

	~~Now let~~'s break down this block of code.		Let's break down this block of code.

	~~First~~, ~~we check~~ if ~~we have~~ a surface, and ~~whether~~ there ~~are reactions~~ on that surface ~~- that's~~ the kinetics() and surface() methods of Wall.		===Check for Surface Reactions===

			The code first loops over each wall, checking if there is a surface phase associated with each wall, and if there is a reaction network on that surface (this happens via calls to the kinetics() and surface() methods of the Wall class):

	<source>		<source>
	~~// compute wall terms~~
	~~size_t loc = m_nsp+2;~~
	~~fill(m_sdot.begin(), m_sdot.end(), 0.0);~~
	for (size_t i = 0; i < m_nwalls; i++) {		for (size_t i = 0; i < m_nwalls; i++) {
	int lr = 1 - 2*m_lr[i];		int lr = 1 - 2*m_lr[i];
Line 175:		Line 180:
	</source>		</source>

	~~Now, if~~ we do have a surface, and we do have kinetics, we do two things:		If we do have a surface, and we do have kinetics, we do two things:
	~~1. Advance~~ surface ~~coverages~~		# Compute surface reaction production rates
	2. Compute the right-hand side of our species coverage equation, to advance the coverages		# Compute the right-hand side of our species coverage equation, to advance the coverages

	~~First~~, ~~we compute some stuff~~ that ~~will be used in finding~~ the RHS of ~~our~~ species coverage equation:		===Compute Surface Production Rates===

			If there is a surface with kinetics, the first thing that's done is to store the inverse site density and number of species, for assembling the RHS of the species coverage equation (the second of the two steps here):

	<source>		<source>
Line 188:		Line 195:
	</source>		</source>

	Next, we set the surface temperature, sync our coverages, and get our net production rates from the surface kinetics:		Next, we set the surface temperature; we sync our coverages (more on this in a moment); and we get our net production rates from the surface kinetics:

	<source>		<source>
Line 196:		Line 203:
	</source>		</source>

	~~Finally~~, we compute the RHS for ~~each of our~~ surface species. ~~This~~ is a net reaction rate~~, and~~ is found by multiplying production rate, inverse site density, and the number of surface sites occupied by species k (that's what <code>surf->size(k)</code> computes; see documentation for the <code>SurfPhase::setCoverages()</code> method):		The Wall class's syncCoverages method sets the coverages in the SurfPhase object (which Wall wraps). As with the get and set methods, this is simply the Wall object wrapping the SurfPhase object such that memory is managed properly. From the Wall class:

			<source>
			void Wall::syncCoverages(int leftright)
			{
			if (leftright == 0) {
			m_surf[0]->setCoverages(DATA_PTR(m_leftcov));
			} else {
			m_surf[1]->setCoverages(DATA_PTR(m_rightcov));
			}
			}
			</source>

			The getNetProductionRates is a virtual method in the Kinetics class, but to speak abstractly about it, what it does is, calculate the net production rate of each species (the number of species here is the TOTAL number of species across ALL phases). So, if we have a gas phase with 100 species and a surface phase with 5 sruface species, the getNetProductionRates must return 105 production rates. These production rates are all in units of <math>\frac{\text{kmol}}{\text{m}^2 \text{s}}</math>.

			From the InterfaceKinetics.cpp class:

			<source>
			void InterfaceKinetics::getNetProductionRates(doublereal* net)
			{
			updateROP();
			m_rxnstoich.getNetProductionRates(m_kk,
			&m_kdata->m_ropnet[0],
			net);
			}
			</source>

			===Compute RHS of Coverage Equation===

			Now that the surface coverages have been updated, and surface rates of production have been computed, we can compute the RHS of the surface coverage equation. The surface coverage equation is an ordinary differential equation that has the same form as the differential equations for gas phase species. The surface species are part of the solution vector, and are part of the set of ODEs that are being solved.

			The RHS for the surface coverage equation is a net reaction rate (not a volumetric reaction rate); it is found by multiplying the surface production rate, the inverse site density, and the number of surface sites occupied by species k (that's what <code>surf->size(k)</code> computes; see documentation for the <code>SurfPhase::setCoverages()</code> method):

	<source>		<source>
Line 209:		Line 247:
	</source>		</source>

	This allows us to compute RHS for surface coverage ODEs.		This allows us to compute RHS for surface coverage ODEs, which goes into the sum variable.

Admin at 18:51, 9 January 2014

2014-01-09T18:51:15Z

← Older revision		Revision as of 18:51, 9 January 2014
Line 1:		Line 1:
	In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.		In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.

			The heterogeneous reaction depends on a number of "moles" of solid species. The number of "moles" of solid species A is the product of the surface coverage (i.e., the "mole fraction") and the site density (i.e., the "total moles"):

			<math>
			N_{A} = \theta_{A} \varrho
			</math>

			where <math>N_{A}</math> is the total "moles" of solid species A, <math>\theta_{A}</math> is the coverage of species A, and <math>\varrho</math> is the site density of the solid.

			This page covers the details of how this surface coverage is dealt with in the Cantera source code, and gives details about how the surface coverage is computed.

	=Overview of Class Hierarchy=		=Overview of Class Hierarchy=

Admin at 18:26, 9 January 2014

2014-01-09T18:26:00Z

← Older revision		Revision as of 18:26, 9 January 2014
Line 1:		Line 1:
	In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.		In Cantera, the surface coverage is equivalent to a mole fraction of a surface species.

			=Overview of Class Hierarchy=

			Coverage is actually stored by a SurfPhase object, which is a manager for all things related to the surface. However, rather than forcing Reactor objects to interface directly with SurfPhase objects, Reactor objects deal with Walls instead. Walls, in turn, wrap SurfPhase objects.

			The SurfPhase object manages the memory directly. The Wall object wraps the SurfPhase object to eliminate the need for Reactors to deal with memory access issues.

			In the Wall class, the coverages are dealt with in three steps: get, set, and calculate.

			* Get coverages - these methods are used when the coverage is needed to initialize the surface species mole fractions.
			* Calculate coverages - these methods are used to calculate the updated coverage, based on the conditions the surface sees changing.
			* Set coverages - once the new coverages are calculated, they need to be set.

			This page covers the [[#Calculating Coverages]], [[#Get Coverages]], and [[#Set Coverages]] methods below.

	=Getting Coverages=		=Getting Coverages=

Admin: /* Setting Coverages */

2014-01-09T18:19:01Z

Setting Coverages

← Older revision		Revision as of 18:19, 9 January 2014
Line 76:		Line 76:

	Again, we're passing a flag to indicate whether the wall is left-handed or right-handed, and then we're passing our solution vector, indexed to the surface species (that's <code>y+loc</code>).		Again, we're passing a flag to indicate whether the wall is left-handed or right-handed, and then we're passing our solution vector, indexed to the surface species (that's <code>y+loc</code>).

			==Wall::setCoverages()==

			In the Wall class, the setCoverages method is not doing anything too fancy. It's basically setting the contents of the Wall's coverage arrays (<code>m_leftcov</code> or <code>m_rightcov</code>) equal to the contents of another array (<code>cov</code>):

			<source>
			void Wall::setCoverages(int leftright, const doublereal* cov)
			{
			if (leftright == 0) {
			copy(cov, cov + m_nsp[0], m_leftcov.begin());
			} else {
			copy(cov, cov + m_nsp[1], m_rightcov.begin());
			}
			}
			</source>

	=Calculating Coverages=		=Calculating Coverages=