Keywords and settings

Revision as of 12:02, 15 April 2020 by Ifilot (talk | contribs) (Networkplot block)
Jump to: navigation, search

Settings block

The list below is an overview of all the keywords that can be placed inside the &settings block. All keywords have a default value, so if these are not specified within the block, then the default value is used.

List of common keywords and their meaning
Keyword Explanation Default value Possible values
TYPE The type of MKMCXX run.
  • SEQUENCERUN : Normal MKMCXX run. Compute a series of single runs at different temperatures.
  • SSITKA : Like SEQUENCERUN, but each single run is run a second time with a different input gas concentration.
  • TPD : Do a single run where temperature is linearly changing during the run.
  • REACTOR : Simple PFR implementation. Only uses first &runs entry and does not support sensitivity analysis.
PRESSURE The total pressure in the gas phase.
  • <0 : Calculate the total pressure from the sum of the starting pressure of the compounds.
  • >0 : Set this total pressure in bar and scale starting pressures proportionately.
-1 (Take starting pressures) float > 0 or negative value
CSTR_RES Residence time of the gas phase in seconds. Defined as the reactor volume divided by the volumetric flow rate into the reactor. This parameter effectively sets the input flow rate. The actual residence time may differ if the overall reaction includes expansion or contraction of the gas volume.
  • <=0 : Gas-phase concentrations are fixed.
  • >0 : Model the gas-phase concentrations as in an isobaric CSTR with in- and outflow. Setting CSTR_RES = 1 is often a good start.
-1 (Fixed gas phase) float > 0 or negative value
CSTR_LOAD Sets the amount of sites (in mole) in the open reactor volume (in m^3).
- Only relevant when CSTR_RES > 0
  • Reasonable values differ very much depending on the system. Often 10^-2 < CSTR_LOAD < 10^2. Increase CSTR_LOAD if conversion is too low. Decrease if conversion is too high.
1e-4 float > 0
USETIMESTAMP Whether to place the output in a new folder which name is based on the current time stamp.
  • 0 : Place all output in a folder called "run".
  • 1 : Generate a folder following the format "<RUNTYPE>_<yyyy>_<mm>_
1 0 or 1
ORDERS Whether to calculate the reaction orders.
- Requires REAGENTS
  • 0 : off
  • 1 : on
0 0 or 1
EACT Whether to calculate the apparent activation energy.
  • 0 : off
  • 1 : on
0 0 or 1
DRC Whether to perform a degree of rate control analysis.
  • 0 : off
  • 1 : on - without drc groups
  • 2 : on - with drc groups
0 0-2 (int)
TDRC Whether to perform a thermodynamic degree of rate control analysis.
  • 0 : off
  • 1 : on
0 0 or 1
REAGENTS List of reagents for which the reaction orders will be calculated. NULL {<Cmp1>},{<Cmp2>},...
KEYCOMPONENTS List of compounds on which the reaction orders, apparent activation energy, DRC, DSC and/or TDRC analysis should be based. NULL x{<Cmp1>},x{<Cmp2>},...
PDRC Whether to include DRC results for every selectivity-component.
- Requires DRC = 2
- Requires selectivity block
  • 0 : Only output DRC results for KEYCOMPONENTS.
  • 1 : Also output DRC results per component in selectivity blocks.
1 0 or 1
DSC Whether to include DSC results for every selectivity-component.
- Requires DRC > 0
- Requires selectivity block
  • 0 : No DSC output.
  • 1 : Output DSC results per component in selectivity blocks.
1 0 or 1
DCGC Whether to include DCGC results for every ASF block.
- Requires DRC = 2
- Requires ASF block
  • 0 : No DCGC output.
  • 1 : Output DCGC results per ASF block.
1 0 or 1
NPAR Maximum number of CPU threads to use (if available).
  • 0-1 : Single-threaded.
  • >=2 : Multi-threaded SEQUENCERUN and sensitivity analysis.
0 int >= 0
TRANSIENT Define the level of detail at which transient results should be stored.
  • 0 : Do not write any transient SEQUENCERUN data.
  • 1 : Write transient concentration and derivative data.
  • 2 : Write transient concentration and derivative data. Also include transient sensitivity/selectivity data.
1 int >= 0
GRAPHDATA Include data files that contain all data points that are plotted in the graphs.
  • 0 : no
  • 1 : yes
0 0 or 1
GRAPHFILTER Apply a filter to graph data that omits small values.
  • 0 : no
  • 1 : yes
1 0 or 1
List of less common keywords and their meaning
Keyword Explanation Default value Possible values
DEBUG Output additional debug statements.
  • 0 : No debug statements.
  • 1-4 : Various levels of debug statements.
0 0-4 (int)
CSTR_REPLACE Replaces starting gas-phase compounds by some other component. E.g. "{He};{CO},{H2}" replaces CO and H2 with He. This does not change inflow concentrations. NULL {<ReplaceCmp>};{<Cmp1>},{<Cmp2>}
RERUN_OUTPUT Define the folder used for re-running sensitivity analysis and graphs. run string
RERUN_GRAPH Whether to re-run graphs from the RERUN_OUTPUT folder.
  • 0 : Regular mkmcxx run.
  • 1 : Re-run graphs.
0 0 or 1
CACHE_WORKPOINT Reuse the sequencerun results as a workpoint in additional routines like DRC.
  • 0 : Do not reuse. Rerun workpoint with zero perturbation.
  • 1 : Reuse the sequencerun results and skip the zero perturbation workpoint.
1 0 or 1
NUMDIFF Resolution of perturbations at each side of the workpoint. 2 int >= 1
ORDERSDIFF Step size used in the linear fitting of reaction orders (fractional pressure).
  • Example values: Wide = 0.1 | Normal = 0.01 | Tight = 0.001
0.01 float > 0
EACTDIFF Step size used in the linear fitting of the apparent activation energy (fractional temperature).
  • Example values: Wide = 0.001 | Normal = 0.0001 | Tight = 0.00001
0.0001 float > 0
DRCDIFF Step size used in the linear fitting for the degree of rate control analysis (fractional k).
  • Example values: Wide = 0.1 | Normal = 0.01 | Tight = 0.001
0.01 float > 0
TDRCDIFF Step size used in the linear fitting for the thermodynamic DRC analysis (absolute dG in J/mol).
  • Example values: Wide = 10 | Normal = 1 | Tight = 0.1
1 float > 0
BOOSTER Multiplier used to speed-up reaction rates; sometimes leads to faster convergence towards the steady-state solution (time is scaled inversely to compensate). 1.0 (regular speed) float > 0
SOLVERTYPE Type of integration method to use for solving the system of ordinary differential equations.
  • 1 : BDF
  • 2 : ADAMS
1 (BDF) 1 or 2 (int)
SOLSTOPTIME Specificies when the solver should force re-evaluation of dydt/jac.
  • 0 : never; use interpolated results for all t-out
  • 1 : force re-evaluation only for the final t-out
  • 2 : force re-evaluation at every t-out
2 0-2 (int)
SOLMAXSTEP Maximum number of internal steps the solver is allowed to take. 5000 int > 0
SOLTESTFAIL Maximum number of test failures before the solver gives up. 70 int > 0
SOLCONVFAIL Maximum number of convergence failures before the solver gives up. 100 int > 0
PRECISION Amount of significant digits to use in output. 10 int > 0
SEQAL Use the output concentrations from completed runs as input for new runs.
  • 0 : Start all runs using specified starting concentrations.
  • 1 : Get starting concentrations from previous completed run.
0 0 or 1
DRCBIN Store binary data of sequencerun to allow re-plotting data.
  • 0 : Don't store binary data.
  • 1 : Store binary data.
0 0 or 1
MAKEPLOTS Whether to create .png and .pdf files of plots.
  • 0 : no
  • 1 : yes
1 0 or 1
HEATMAP Whether to create heatmap graphs for DRC/DSC results.
  • 0 : no
  • 1 : yes
1 0 or 1
COLORBLIND Change the order of the graph-coloring for (slightly) improved readability.
  • 0 : no
  • 1 : yes
0 0 or 1
PRINTLIST Generate some extra debug lines with the initial and final concentrations.
- Requires DEBUG > 1
  • 0 : no
  • 1 : yes
1 0 or 1
WERROR Interpret input warnings as errors.
  • 0 : no
  • 1 : yes
0 0 or 1
RELDERIV Plot relative derivatives.
  • 0 : no
  • 1 : yes
0 0 or 1
SELECTIVITY_CAP Force upper limit for selectivity data to prevent unreadable selectivity graphs. NULL float > 0
MINIMUM_BAR Set a minimum reaction barrier height based on max(Ef,Eb). NULL float > 0
MAXIMUM_BAR Set a maximum reaction barrier height based on max(Ef,Eb). NULL float > 0
SIMPLE_LAT_FAC Scaling factor for lateral interactions. 1.0 float
SIMPLE_LAT_CLAMP Upper bound for the change in barrier height (J/mol) from lateral interactions. 250e3 float
SIMPLE_LAT_DIFF Convert supplied integral simple_lat to differential_lat.
- Experimental feature
  • 0 : no
  • 0 : yes
0 0 or 1
List of electrochemistry and diffusion model specific keywords and their meaning
Keyword Explanation Default value Possible values
POTAXIS Sets the x-axis for the SEQUENCERUN range plot.
  • 0 : temperature
  • 1 : electrochemical potential
0 0 or 1
pH Sets the pH that is used to determine the RHE potential. 0 float
DIFF Whether to generate plots of diffusion layer concentrations.
  • 0 : no
  • 1 : yes
0 0 or 1
NdX Number of discretized layers in diffusion layer
  • Note: 1 layer is used for the bulk boundary
100 float > 0
dX Thickness of one discretized diffusion layer
  • Note: Total diffusion layer thickness = (NdX-1)*dX
1e-8 float > 0
DIFF_LOAD Conversion factor for diffusion-surface interface (mol sites / m2) 1e-5 float > 0
DIFF_START_ZERO Whether to initialize diffusion layers to zero or use bulk.
  • 0 : use bulk concentrations
0 : initialize to zero 0 or 1
DIFF_POT Extra potential over diffusion layer that influences diffusion of charged particles
- Experimental feature
0 float
DIFF_PHASE Set the phase of the diffusion layer (influences boundary conditions).
  • LIQUID : Use mol/dm3 conversions
  • GAS : Use ideal gas law with bar/m3 conversions
List of networkplot-specific keywords and their meaning
Keyword Explanation Default value Possible values
NETWORK Allow creation of network graphs.
  • 0 : no
  • 1 : yes
1 0 or 1
NETWORK_RATES Also print forward and backward rates in the network graphs.
  • 0 : no
  • 1 : yes
0 0 or 1
NETWORK_STRICT Merge multiple edges between nodes into one edge.
  • 0 : no
  • 1 : yes
1 0 or 1
NETWORK_FLUX Generate dedicated flux output.
  • 0 : no
  • 1 : yes
0 0 or 1
NETWORK_NODAL_PROD Show connected products in nodal-recall chain.
- Requires setting NODAL parameters in &networkplot
  • 0 : no
  • 1 : yes
  • 2 : yes, and also trace the chain of the connected product (except for NODAL_ROOT)
0 0-2 (int)
GIBBS Calculate gibbs free energy barriers at the start and at the end coverages
  • 0 : no
  • 1 : yes
0 0 or 1
List of TPD-specific keywords and their meaning
Keyword Explanation Default value Possible values
ABSTOL Set the absolute tolerance for a TPD run. 1e-12 float > 0
RELTOL Set the relative tolerance for a TPD run. 1e-8 float > 0
TIME Set the simulation time for a TPD run. NULL float > 0
TSTART Starting temperature for a TPD run. NULL float > 0
TEND Temperature reached at the end of the TPD run. NULL float > 0
TPD_EQ Try to equilibrate the system before starting the TPD run.
  • 0 : no
  • 1 : yes
0 0 or 1
List of REACTOR-specific keywords and their meaning
Keyword Explanation Default value Possible values
F_MOLE In-flow of a PFR type reactor. NULL float > 0
A_REAC Cross-sectional area of a PFR type reactor in m^2. NULL float > 0
L_REAC Length of a PFR type reactor in m. NULL float > 0
RHO_SITES Site density in mole sites / m^2 NULL float > 0
BET Surface area in m^2 / g NULL float > 0
CATALYST_LOADING Ratio of active catalyst material on support kg/kg NULL float > 0
CATALYST_DENSITY Density of the catalyst bed in kg / m^3 NULL float > 0
VOID_FRACTION Void fraction of the reactor NULL float > 0
REACNRSTEPS Number of discrete slabs in the PFR. 30 int > 0
List of deprecated keywords and their meaning
Keyword Explanation
GNUPLOT Whether to output GNUPlot-style graphs.
CSTR Whether to use the CSTR module or not.
  • The CSTR functionality now fully depends on the value of CSTR_RES.
JACOBIAN Whether to use the custom MKMCXX JACOBIAN.
  • 0 : use default SUNDIALS jacobian (default)
  • 1 : use custom MKMCXX jacobian (discontinued)
DAMPENING Whether to enable dampening to old implementation of lateral interactions.
  • 0 : no (default)
  • 1 : yes
DAMPENING Lower coverage bound for old implementation of lateral interactions.
  • 0.0 (float) by default
DEFAULT_LAT Allows old lateral repulsion parameters A and B to be set for all compounds.
  • <float>;<float>
MAXIMUM_RATE Set a maximum reaction rate. (in s-1 - e.g. 1e6)
  • Not implemented

Graphs block

Inside the graphs block, you can set the colors used in the non-GNUPLOT graphs for specific components. On each line, you place the compound between curly brackets followed by the RGB color code. For example:

# fix colors for particular compounds
{A*} E74C3D
{B*} F29C1F
{C*} 287FB9
{*}  15A086

Selectivity block


Inside the selectivity block, you can specify mole balances on which basis you calculate selectivity and degree of selectivity control graphs. You need to specify a name, a key component and one or more products (typically more than one, else the concept of selectivity is rather trivial). The name will be used in the generation of the corresponding graph file, so please use a safe name (i.e. no spaces and no special characters!)

species_balance; {A}; {E},{F}

In the above example, the name of the mole balance block is "species_balance", the key component is A and the products of interest are E and F. A detailed example on how to use this block is explained here.


Often, the stoichiometry of the key component and the products is not simply a 1:1 ratio. To account for this difference, you need to put the stoichiometric coefficient in front the compound. The stoichiometric coefficient is simply the number of key components which need to be consumed to produce one product. To illustrate this, below an example for CO hydrogenation towards C1-C3 hydrocarbons is provided.

carbon_balance; {CO}; {CH4}, 2{CH2CH2}, 2{CH3CH3}, 3{CH2CHCH3}, 3{CH3CH2CH3}

For complex systems like the Fischer-Tropsch synthesis reaction the number of products can be quite large. To help prevent very long lines in the input file we allow the selectivity definition to be separated over multiple lines. These lines are additive, meaning that the example above can also be written as follows:

carbon_balance; {CO}; {CH4}
carbon_balance; {CO}; 2{CH2CH2}, 2{CH3CH3}
carbon_balance; {CO}; 3{CH2CHCH3}, 3{CH3CH2CH3}


carbon_balance; {CO}; {CH4}
carbon_balance; {CO}; 2{CH2CH2}
carbon_balance; {CO}; 2{CH3CH3}
carbon_balance; {CO}; 3{CH2CHCH3}
carbon_balance; {CO}; 3{CH3CH2CH3}

Multiple selectivity balances may be defined in the same selectivity group, e.g.:

carbon_balance; {CO}; {CH4}
carbon_balance; {CO}; 2{CH2CH2}, 2{CH3CH3}
carbon_balance; {CO}; 3{CH2CHCH3}, 3{CH3CH2CH3}
ethylene_vs_ethane; {CO}; 2{CH2CH2}, 2{CH3CH3}
propylene_vs_propene; {CO}; 3{CH2CHCH3}, 3{CH3CH2CH3}

ASF block

The ASF block allows the MKMCXX to generate Anderson–Schulz–Flory distribution plots of the (Fischer–Tropsch) reaction products. Defining an ASF group is similar to defining a selectivity group. Every line starts with the name of the ASF group, and ends with the products. For example, here is the definition for a ASF plot of carbon numbers 1 to 10.

asf_plot; 5; {CH4}
asf_plot; 5; 2{CH2CH2},2{CH3CH3}
asf_plot; 5; 3{CH2CH-C1},3{CH3CH2-C1}
asf_plot; 5; 4{CH2CH-C2},4{CH3CH2-C2}
asf_plot; 5; 5{CH2CH-C3},5{CH3CH2-C3}
asf_plot; 5; 6{CH2CH-C4},6{CH3CH2-C4}
asf_plot; 5; 7{CH2CH-C5},7{CH3CH2-C5}
asf_plot; 5; 8{CH2CH-C6},8{CH3CH2-C6}
asf_plot; 5; 9{CH2CH-C7},9{CH3CH2-C7}
asf_plot; 5; 10{CH2CH-C8},10{CH3CH2-C8}

Instead of the key component there is now the number 5. This number is used as a starting point for determining the slope of the ASF distribution. In this example the corresponding chain-growth probability is calculated for the carbon-number range of 5-10. The 'stoichiometry'-coefficients, e.g. 7{CH2CH-C5}, are used to identify the number of carbon atoms in the product.

Networkplot block

To quickly visualize the flux from reactants to products the MKMCXX code includes automated network plot creation. For moderately large systems this plot can quickly get very complex. The networkplot block can be used to guide MKMCXX in creating a readable graph.

EXCLUDE_NODES = {*s},{H*s}
EXCLUDE_NODES = {*t},{H*t}

In the example above the ROOT_NODE tag sets the compound to which all fluxes should be normalized. In this case the consumption of CO will be set to unity. The EXCLUDE tags make sure that irrelevant nodes are not included in the plot. Specific nodes can be excluded by the (additive) EXCLUDE_NODES tags. The (also additive) EXCLUDE_REGEX tag finds nodes matching the supplied regular expression. The EXCLUDE_LIMIT tag controls which links between nodes are visible. In this case, all links with a normalized flux less than 1e-4 are removed. Nodes without any links are also removed from the plot.

Nodal Recall

MKMCXX now includes a new (experimental) way of generating network plots. This 'Nodal Recall' method uses a shortest paths algorithm comparable to Dijkstra's algorithm and the Bellman-Ford algorithm.

Relevant keywords and example values are:

NODAL_START = {CO},{H2},{*t},{*s}
NODAL_EXCLUDE = {*s},{*t}
NODAL_END = {H2O},{CH4},{CH2CH2},{CH3CH3}

The algorithm will try to generate the paths with the highest flux from the NODAL_START nodes to the NODAL_END nodes. NODAL_EXCLUDE nodes will not be used in these paths.

The NETWORK_NODAL_PROD setting (in the &settings block) determines whether byproducts should be traced. For NETWORK_NODAL_PROD = 2 the user should define NODAL_ROOT like:


In the example above the algorithm will try to trace the flux chain from a product like CH4 back to the reactants CO and H2. Somewhere in this chain the adsorbed CO* will dissociate into C* and O*. This C* is the node that ultimately leads to CH4.

  • With NETWORK_NODAL_PROD = 0 the O* will not be printed as a branch in the chain.
  • With NETWORK_NODAL_PROD = 1 the O* will be printed, but the by-product chain will not be evaluated.
  • With NETWORK_NODAL_PROD = 2 the O* will be printed, and the by-product chain will be evaluated to reach the NODAL_ROOT, which in this case is H2O.