Skip to content

Topology Models

Topology models extend the intrinsic kinetic law of a reaction with an additional multiplicative factor that depends on site topology.

This is mainly useful for multisite models, where a reaction may depend not only on the coverages of the participating species, but also on the abundance of the required site motif, such as an S1-S2 pair.

Why Topology Models Exist

In a standard mean-field reaction, the rate is built from:

  • the kinetic model, which defines the forward and backward rate constants
  • the participating surface coverages
  • the participating gas-phase activities, when relevant

For multisite reactions, that is not always enough. A cross-site elementary step such as

{E*S1}+{O*S2}=>{EO*S1}+{*S2}

depends on the availability of S1-S2 site pairs. A topology model supplies that additional factor.

Conceptually, MKMCXX evaluates

\[ r = f_\mathrm{topology} \; k \; \prod_i \theta_i^{\nu_i} \; \prod_j a_j^{\mu_j} \]

where:

  • \(k\) comes from the kinetic model
  • \(f_\mathrm{topology}\) comes from the topology model
  • \(\theta_i\) are the participating surface coverages
  • \(a_j\) are the participating gas-phase activities

If no topology model is attached, MKMCXX uses the default identity factor:

\[ f_\mathrm{topology} = 1 \]

Syntax

Reactions may carry more than one model attachment. The first @ ... clause defines the kinetic model. Additional @ ... clauses add extra behavior such as topology factors.

reactions {
  {E*S1}+{O*S2}=>{EO*S1}+{*S2}
    @ ArrheniusDefault(Vf=1e13, Vb=1e13, Eaf=124441, Eab=240000)
    @ PairMeanField(topology=topo)
}

Topology models may also use reusable let bindings:

let topo = PairStatistics(pair_densities={S1-S1=1.0, S1-S2=0.5, S2-S2=1.0})

The participating site names come from the site="..." attributes assigned in the components block.

TopologyDefault

TopologyDefault() is the implicit fallback when no topology model is attached.

Behavior

It leaves the rate law unchanged:

\[ f_\mathrm{topology} = 1 \]

Example

reactions {
  {E}+{*S1}=>{E*S1}
    @ HertzKnudsenDefault(Asite=4.43e-28, m=28, theta=2.8, sigma=1, S=1, Edes=91688)
}

This is equivalent to:

reactions {
  {E}+{*S1}=>{E*S1}
    @ HertzKnudsenDefault(Asite=4.43e-28, m=28, theta=2.8, sigma=1, S=1, Edes=91688)
    @ TopologyDefault()
}

PairMeanField

PairMeanField(...) is the current topology-aware model for mean-field multisite reactions.

Purpose

It scales the rate of a reaction by a topology-dependent prefactor derived from the participating site motif.

For example:

  • a single-site step on S1 may scale with the S1 site abundance
  • a pair step on S1-S2 scales with the S1-S2 pair statistic supplied by the topology source

Parameters

  • topology A topology source that provides the required site or pair statistics.

Example

let topo = PairStatistics(pair_densities={S1-S1=1.0, S1-S2=0.5, S2-S2=1.0})

reactions {
  {E*S1}+{O*S2}=>{EO*S1}+{*S2}
    @ ArrheniusDefault(Vf=1e13, Vb=1e13, Eaf=124441, Eab=240000)
    @ PairMeanField(topology=topo)
}

PairStatistics

PairStatistics(...) is a topology source that explicitly specifies the available pair motifs in the mean-field model.

Parameters

  • pair_densities An object mapping site-pair names to their topology factors.

Pair names use the site identifiers declared in the component metadata:

pair_densities={S1-S1=1.0, S1-S2=0.5, S2-S2=1.0}

Interpretation

These numbers represent the relative abundance of each site pair in the topology-aware mean-field model.

For a reaction that requires an S1-S2 motif, PairMeanField looks up the corresponding S1-S2 entry and multiplies the intrinsic rate by that factor.

Example

let s1 = {site="S1", site_density=1.0}
let s2 = {site="S2", site_density=0.5}

let topo = PairStatistics(
  pair_densities={
    S1-S1=1.0,
    S1-S2=0.5,
    S2-S2=1.0
  }
)

components {
  *S1   {phase=surface, init=1.0, tags=[emptysite], *s1},
  E*S1  {phase=surface, init=0.0, *s1},
  EO*S1 {phase=surface, init=0.0, *s1},
  *S2   {phase=surface, init=1.0, tags=[emptysite], *s2},
  O*S2  {phase=surface, init=0.0, *s2}
}

reactions {
  {E*S1}+{O*S2}=>{EO*S1}+{*S2}
    @ ArrheniusDefault(Vf=1e13, Vb=1e13, Eaf=124441, Eab=240000)
    @ PairMeanField(topology=topo)
}

Site Names and Pair Keys

Pair statistics should use the real site names from the component metadata.

Good:

pair_densities={S1-S2=0.5}

Not recommended:

pair_densities={A-B=0.5}

This keeps the input file self-consistent and allows the reaction topology to be inferred directly from the participating compounds.

Relationship to site_density

site_density and pair_densities are related, but they are not the same thing.

  • site_density describes the abundance of each individual site family
  • pair_densities describe the abundance of neighboring site motifs such as S1-S1, S1-S2, and S2-S2

Two surfaces may have the same site-density ratio but different pair statistics, depending on how the sites are arranged.

Current Scope

The current implementation supports topology-aware mean-field rate scaling for single-site and pair-site reactions.

The current manual does not describe:

  • explicit lattice or tile master-equation models
  • higher-order motifs such as triplets or larger ensembles
  • automatically generated pair statistics from a lattice model

For a worked dual-site example, see the case study Dual-Site Models.